Webhooks
The gateway sends a signed JSON POST to your HTTPS endpoint when a payment, a payout or a subscription changes state. Treat a webhook as a hint: before you act on it, read the object through the API and use what the API returns.
On this page
Endpoints
- You add endpoints in the Webhooks page of your dashboard. Each endpoint belongs to one mode: a test endpoint receives only test events and a live endpoint only live ones. You can have at most 5 per mode.
- The signing secret (
whsec_...) is shown once, when you create the endpoint. If you lose it, create a new endpoint. - The URL must be
https://, without a user name or password, and at most 2048 characters long. Every address its host resolves to must be public: private, loopback, link-local and other reserved addresses are refused when you save the endpoint and again before every send.
The request
POST /your/path HTTP/1.1
Content-Type: application/json
User-Agent: CreativePayments-Webhooks/1
CP-Event-Id: evt_3f2a9c0d81b4e6f70a1c2d3e
CP-Signature: t=1793966400,v1=5d0c...e9
{"id":"evt_3f2a9c0d81b4e6f70a1c2d3e","type":"payment.paid","created":1793966400,"livemode":true,"data":{...}}idis the event id: the same on every attempt, every resend and every endpoint.createdis the time of the state change, in unix seconds, not the time of sending.- Every attempt sends the same body, byte for byte. Only the signature timestamp changes.
Verifying the signature
CP-Signature is t=<unix seconds>,v1=<hex>. The hex value is the HMAC-SHA256, keyed with your endpoint secret, of the string <t>.<raw body>. Verify the raw body exactly as you received it, not a parsed and re-serialized one, and reject a timestamp more than 5 minutes away from your clock so a captured request cannot be replayed.
import { createHmac, timingSafeEqual } from 'node:crypto';
const TOLERANCE_SECONDS = 5 * 60;
/** rawBody: the request body as a string, exactly as received. */
export function verifyWebhook(secret, header, rawBody, nowSeconds = Math.floor(Date.now() / 1000)) {
const match = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(header ?? '');
if (!match) return false;
const timestamp = Number(match[1]);
if (Math.abs(nowSeconds - timestamp) > TOLERANCE_SECONDS) return false;
const expected = createHmac('sha256', secret).update(`${match[1]}.${rawBody}`).digest();
const given = Buffer.from(match[2], 'hex');
return given.length === expected.length && timingSafeEqual(given, expected);
}With Express, read the body with express.raw({ type: 'application/json' }) and pass req.body.toString('utf8').
Delivery and retries
- At least once. The same event can arrive more than once. Remove duplicates by the event
id(or theCP-Event-Idheader). - No order. Events can arrive in any order: act on the state you read from the API.
- Success is any 2xx answer within 10 seconds, for connecting, sending and receiving the answer. Answer first, then do the work.
- No redirects. A 3xx answer is a failed attempt. Your certificate must be valid for the host and issued by a publicly trusted authority.
- Retries: a failed attempt is retried after 1 minute, 5 minutes, 30 minutes, 2 hours and 12 hours: 6 attempts in all. After the sixth failure the delivery is marked failed.
- The dashboard shows the newest 100 deliveries with their status, attempts, last status code and an error code. You can resend a delivered or failed delivery; it keeps its event id and body.
Event catalogue
| Event | Sent when | data |
|---|---|---|
payment.paid | A payment was paid. | The payment |
payment.failed | A payment failed or was canceled; reason is failed or canceled. | The payment |
payment.expired | A payment expired unpaid. | The payment |
payout.submitted | A payout of a paid live payment was sent to your payout address. Live only. | The payout |
payout.failed | A submitted payout was canceled at the payout processor and not paid. Live only. | The payout |
subscription.activated | The first payment was paid; the subscription is active. | The subscription |
subscription.canceled | The subscription was canceled. | The subscription |
subscription.completed | All times charges were made. | The subscription |
subscription.abandoned | The first payment ended unpaid; no subscription was started. | The subscription |
Payment events
The data of a payment event carries the price (amount, currency), the charge, the provider_charge, your description and metadata, and subscription_id for a recurring charge. See Amounts, currencies and VAT.
{
"id": "evt_3f2a9c0d81b4e6f70a1c2d3e",
"type": "payment.paid",
"created": 1793966400,
"livemode": true,
"data": {
"id": "pay_0123456789abcdefghjkmnpq",
"status": "paid",
"amount": "49.00",
"currency": "USD",
"charge": {
"amount": "43.78",
"currency": "EUR",
"fx_rate": "1.1193",
"fx_date": "2026-11-05",
"net_amount": "43.78",
"vat_amount": "0.00"
},
"provider_charge": null,
"description": "Order 1001",
"metadata": {
"order_id": "1001"
},
"paidAt": "2026-11-06T12:00:00.000Z"
}
}Payout events
Payout events are always live and never contain the payout address. A payout submitted again later sends a new event with a new id.
{
"id": "evt_5c6d7e8f9a0b1c2d3e4f5a6b",
"type": "payout.submitted",
"created": 1793966400,
"livemode": true,
"data": {
"id": "pyo_0123456789abcdefghjkmnpq",
"paymentId": "pay_0123456789abcdefghjkmnpq",
"status": "submitted",
"coin": "BTC",
"currency": "EUR",
"amount": "47.47",
"fee": "1.13",
"networkFee": "0.40",
"submittedAt": "2026-11-06T12:01:00.000Z"
}
}Subscription events
The data of a subscription event is the subscription object, as the API returns it. Before you act, read it with GET /v1/subscriptions/{id}.
{
"id": "evt_4e5f6a7b8c9d0e1f2a3b4c5d",
"type": "subscription.activated",
"created": 1793966400,
"livemode": true,
"data": {
"id": "sub_0123456789abcdefghjkmnpq",
"object": "subscription",
"status": "active",
"amount": "49.00",
"currency": "EUR",
"interval": "1 month",
"times": 12,
"description": "Plus plan, monthly",
"metadata": {
"plan": "plus",
"customer_id": "17"
},
"livemode": true,
"first_payment_id": "pay_7777777777abcdefghjkmnpq",
"next_charge_date": "2026-12-18",
"created": "2026-11-18T10:00:00.000Z",
"activated_at": "2026-11-18T10:05:00.000Z",
"canceled_at": null
}
}