DevelopersHomeAPI referenceGuidesChangelogMarketplacePartnersCommunityStatus

Webhooks

Register an endpoint, verify the signature, handle repeats, replay.

Register

POST /v1/webhook_endpoints with url and optional events. The signing secret is in that response only. An address on a private network is refused.

Verify

Each delivery carries X-Signature: t=<unix>,v1=<hex>, where the hex is HMAC-SHA256, keyed by the secret, of the timestamp, a dot and the raw body. Refuse anything more than five minutes from your clock. Compare in constant time, over the raw bytes, before parsing.

import { createHmac, timingSafeEqual } from "node:crypto";
const [t, v1] = header.split(",").map((p) => p.split("=")[1]);
const want = createHmac("sha256", secret).update(t + "." + rawBody).digest();
const ok = Math.abs(Date.now() / 1000 - Number(t)) <= 300
  && timingSafeEqual(want, Buffer.from(v1, "hex"));

The Node and Java SDKs do this for you, and are tested against vectors from the server's own signing code.

Handle repeats

Delivery is at least once. X-Event-Id stays the same across attempts, so key your work on it. X-Delivery-Attempt counts them. Answer 2xx quickly and do the work afterwards. An endpoint that keeps failing is switched off.

Events

payment.captured, payment.failed, payment.pending, payment.authorised, payment.double_capture, refund.processed, refund.failed, authorisation.failed, authorisation.expired, authorisation.voided, mandate.updated, order.state_changed, shipment.updated, shipment.ndr, return.updated, subscription.updated, invoice.updated.

Payment and refund events carry the metadata you set on the payment.

When one does not arrive

GET /v1/webhook_events?q=PAYMENT_ID finds the event with its attempts and last error, GET /v1/webhook_events/{id}/deliveries lists every try, POST /v1/webhook_endpoints/{id}/test sends one now, and POST /v1/webhook_events/{id}/replay sends an event again. Rotating a secret with rotate_secret takes effect at once, so change your side straight after.