Skip to content
Creative Payments

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

A webhook deliveryHTTP
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":{...}}
  • id is the event id: the same on every attempt, every resend and every endpoint.
  • created is 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.

Verify a webhook signature (Node.js)JavaScript
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 the CP-Event-Id header).
  • 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

EventSent whendata
payment.paidA payment was paid.The payment
payment.failedA payment failed or was canceled; reason is failed or canceled.The payment
payment.expiredA payment expired unpaid.The payment
payout.submittedA payout of a paid live payment was sent to your payout address. Live only.The payout
payout.failedA submitted payout was canceled at the payout processor and not paid. Live only.The payout
subscription.activatedThe first payment was paid; the subscription is active.The subscription
subscription.canceledThe subscription was canceled.The subscription
subscription.completedAll times charges were made.The subscription
subscription.abandonedThe 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.

payment.paidJSON
{
  "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.

payout.submittedJSON
{
  "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}.

subscription.activatedJSON
{
  "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
  }
}