Webhooks

A webhook is an HTTP POST from Creptapay to a URL you control, sent when something happens in your account. They are how you find out a payment confirmed on-chain without polling for it, and the only reliable way to know a subscription has lapsed. Register endpoints in the dashboard under Developer → Webhooks, or over the API — see Managing endpoints below.

The envelope

Every delivery has the same shape. Only data changes between events.

{
  "event": "payment.paid",
  "environment": "production",
  "data": { "...": "the object the event is about" },
  "timestamp": 1784849494900
}

Field
`event`	The event name, e.g. `payment.paid`. Always switch on this.
`environment`	`sandbox` or `production`. Never trust the endpoint URL to tell you which.
`data`	The full object, in the same shape the REST API returns it.
`timestamp`	Unix milliseconds when we built the request. Also the `t` in the signature.

Headers

Header
`X-Creptapay-Signature`	`t=<unix ms>,v1=<hex>`. Verify it on every request.
`X-Creptapay-Event`	The event name, so you can route before parsing.
`X-Creptapay-Environment`	`sandbox` or `production`.
`User-Agent`	`Creptapay-Webhook-Dispatcher/1.0`

Verify the signature on every request before you act on it — see Verify Signature. An unverified webhook endpoint is a URL that anyone who guesses it can use to mark orders as paid.

Delivery

Be aware of how delivery actually behaves before you build on it:

We attempt each delivery once. If your endpoint is down, times out, or returns a non-2xx status, the event is recorded as failed and is not retried automatically. Resend it from Developer → Logs in the dashboard.

Respond within 10 seconds. We give up after that and mark the delivery failed, even if your handler eventually finishes. Acknowledge with a 200 first and do the slow work afterwards.
Return 2xx to acknowledge. Any other status counts as a failure.
Order isn’t guaranteed. Deliveries go out in parallel, so payment.paid can reach you before payment.created. Treat each event as a statement about the object’s current state rather than a step in a sequence.
Handle duplicates. A resent delivery repeats an event you may already have processed. Key your handler on the object’s id and the event name, and make repeat deliveries a no-op.
Reconcile, don’t rely. Because there are no automatic retries, a webhook outage on your side loses events. For anything that must not be missed — granting access, releasing goods — reconcile against the REST API on a schedule as well.

Environments

An endpoint is scoped to sandbox, to production, or to both. One registered for a single environment only ever receives that environment’s events, so you can point sandbox at a tunnel on your laptop and production at your real server without them crossing. Each environment signs with its own secret key. A live delivery is signed with your live key, and you cannot verify it with your test key.

Event catalogue

Payments

Event	Fires when
`payment.created`	A checkout opened and a deposit address was issued.
`payment.paid`	Funds confirmed on-chain. Fulfil the order here.
`payment.underpaid`	Less arrived than expected. The balance can still be sent.
`payment.expired`	The window closed without full payment.

data is the payment object:

{
  "event": "payment.paid",
  "environment": "production",
  "data": {
    "id": "60d0fe4f5311236168a109ca",
    "reference": "CP-A1B2C3D4E5",
    "customer": {
      "id": "60d0fe4f5311236168a109c9",
      "first_name": "Chidera",
      "last_name": "Okonkwo",
      "email": "chidera@example.com",
      "phone": "+2348012345678"
    },
    "currency": "USD",
    "crypto_currency": "USDC",
    "network": "BASE",
    "rate": 1,
    "crypto_amount": 21,
    "amount_paid": 21,
    "amount": 21,
    "address": "0x1234567890123456789012345678901234567890",
    "fees": 0.21,
    "total": 21,
    "description": "Invoice Payment",
    "line_items": [{ "name": "Item Name", "amount": 10.5, "quantity": 2 }],
    "status": "paid",
    "type": "api",
    "subscription": null,
    "billing_period_start": null,
    "billing_period_end": null,
    "business": "60d0fe4f5311236168a109c8",
    "allowed_currencies": [],
    "checkout_url": "https://pay.creptapay.com/CP-A1B2C3D4E5",
    "redirect_url": null,
    "metadata": null,
    "tx_hash": "0xabcdef1234567890...",
    "confirmations": 12,
    "required_confirmations": 12,
    "expires_at": "2026-07-24T14:40:15Z",
    "createdAt": "2026-07-24T14:08:52Z",
    "updatedAt": "2026-07-24T14:10:15Z",
    "transactionHash": "0xabcdef1234567890..."
  },
  "timestamp": 1784849495000
}

transactionHash is added on payment.paid and payment.underpaid; it is the same value as tx_hash, kept for older integrations. status is overpaid rather than paid when more arrived than was owed. Both mean the payment settled — check for either, or use payment.paid as the trigger and read amount_paid for the figure.

Subscriptions

Event	Fires when	What to do
`subscription.created`	Someone subscribed. Nothing paid yet.	Nothing — wait for activation.
`subscription.activated`	The first payment landed.	Grant access.
`subscription.charged`	A renewal was paid; the next period started.	Extend access.
`subscription.past_due`	The period ended unpaid; grace has begun.	Your call — warn, restrict, or wait.
`subscription.expired`	Grace ran out.	Revoke access.
`subscription.cancellation_scheduled`	It will end when the paid period does.	Nothing yet.
`subscription.canceled`	Ended, immediately or at the period’s end.	Revoke access.
`subscription.paused`	Billing is on hold; nothing is owed while it is.	Usually keep access.
`subscription.resumed`	Billing restarted from today.	—
`subscription.updated`	A subscriber was moved onto the plan’s current terms.	Re-read the price.

The two that matter are subscription.activated and subscription.expired. Wire those and you have a working integration; the rest is refinement. data is the subscription object, with plan and customer always expanded:

{
  "event": "subscription.charged",
  "environment": "production",
  "data": {
    "id": "6712f0a1b9c4e2d3f4a5b6c7",
    "reference": "SUB-K3F9A2QP",
    "status": "active",
    "collection_mode": "invoice",
    "checkout_url": "https://pay.creptapay.com/SUB-K3F9A2QP",
    "amount_due": { "amount": 49, "currency": "USD" },
    "terms": {
      "amount": 49,
      "currency": "USD",
      "interval": "month",
      "interval_count": 1,
      "grace_days": 7,
      "allowed_currencies": ["USDC"],
      "captured_at": "2026-01-15T09:22:11Z"
    },
    "on_legacy_terms": false,
    "plan": {
      "id": "6712f0a1b9c4e2d3f4a5b6c7",
      "name": "Pro",
      "amount": 49,
      "currency": "USD",
      "interval": "month",
      "interval_count": 1,
      "grace_days": 7
    },
    "customer": {
      "id": "60d0fe4f5311236168a109c9",
      "name": "Chidera Okonkwo",
      "email": "chidera@example.com"
    },
    "current_period_start": "2026-02-15T09:22:11Z",
    "current_period_end": "2026-03-15T09:22:11Z",
    "next_billing_at": "2026-03-15T09:22:11Z",
    "grace_ends_at": "2026-03-22T09:22:11Z",
    "trial_ends_at": null,
    "cancel_at_period_end": false,
    "canceled_at": null,
    "cancel_reason": null,
    "latest_payment": {
      "id": "60d0fe4f5311236168a109ca",
      "reference": "CP-A1B2C3D4E5",
      "status": "paid",
      "amount": 49,
      "currency": "USD",
      "crypto_currency": "USDC",
      "network": "BASE",
      "tx_hash": "0xabcdef1234567890...",
      "billing_period_start": "2026-02-15T09:22:11Z",
      "billing_period_end": "2026-03-15T09:22:11Z",
      "createdAt": "2026-02-15T09:20:02Z"
    },
    "payments_count": 2,
    "failed_attempts": 0,
    "last_failure_reason": null,
    "metadata": null,
    "createdAt": "2026-01-15T09:22:11Z",
    "updatedAt": "2026-02-15T09:22:14Z"
  },
  "timestamp": 1784849495000
}

Read the price from terms, not from plan. terms is what this subscriber actually pays, frozen when they signed up; plan may since have been repriced for new customers. When the two differ, on_legacy_terms is true. See Subscriptions.

Subscription payments fire the payment events too. A renewal arrives as a payment.paid with type: "subscription", the subscription’s id in subscription, and the cycle it covers in billing_period_start and billing_period_end — so an existing payments integration keeps working unchanged. If you handle both, make sure you don’t fulfil twice.

Managing endpoints

In the dashboard: Developer → Webhooks → Add endpoint, then pick the events you want. Developer → Logs shows every delivery with the response we got back, and lets you resend one.

Over the API

Endpoints can also be managed with your secret key, which is how an installable integration registers itself. The key decides the environment — a test key registers a sandbox endpoint, a live key a production one.

Registering is an upsert keyed on the URL. Posting the same URL again updates its event list instead of creating a second endpoint, so an integration can call this on every startup without piling up duplicates.

curl -X POST https://api.creptapay.com/v1/webhooks \
  -H "x-api-key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.yourshop.com/webhooks/creptapay",
    "events": ["payment.paid", "subscription.activated", "subscription.expired"],
    "description": "Order fulfilment"
  }'

Field
`url`	Required. Must be HTTPS — `http://localhost` is allowed while developing.
`events`	Event names from the catalogue above, or `["*"]` for everything including events added later. Omit it and you get `payment.paid`, `payment.underpaid` and `payment.expired`.
`description`	Optional label, up to 200 characters.

An unknown event name is rejected with Unsupported events: ... rather than silently ignored, so a typo fails loudly instead of leaving you waiting for a delivery that never comes. List your endpoints for the key’s environment:

curl https://api.creptapay.com/v1/webhooks \
  -H "x-api-key: sk_live_..."

Remove one by URL:

curl -X DELETE "https://api.creptapay.com/v1/webhooks?url=https://api.yourshop.com/webhooks/creptapay" \
  -H "x-api-key: sk_live_..."

Send a test delivery to check an endpoint is reachable and your signature check passes, before you depend on it:

curl -X POST https://api.creptapay.com/v1/webhooks/test \
  -H "x-api-key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://api.yourshop.com/webhooks/creptapay" }'

This POSTs a signed webhook.test event — same envelope, same headers, same signature — and reports back what your server returned:

{ "ok": true, "status": 200, "error": null }

The URL doesn’t have to be registered first. Handle webhook.test by verifying the signature and returning 200; there’s nothing to act on.

Securing your endpoint

Verify the signature on every request, and only then act on the payload. Step by step, with code for Node, Python, PHP and Java: Verify Signature.

Getting Started

Plugins & SDKs

Webhooks

The envelope

Headers

Delivery

Environments

Event catalogue

Payments

Subscriptions

Managing endpoints

Over the API

Securing your endpoint

​The envelope

​Headers

​Delivery

​Environments

​Event catalogue

​Payments

​Subscriptions

​Managing endpoints

​Over the API

​Securing your endpoint

The envelope

Headers

Delivery

Environments

Event catalogue

Payments

Subscriptions

Managing endpoints

Over the API

Securing your endpoint