Receiving and verifying webhooks

Webhooks send an HTTPS POST to your endpoint when something happens, for example payment.succeeded, invoice.paid or subscription.canceled.

Verifying signatures

Each request includes an x-platform-signature header like t=1761234567,v1=5257a8…. Compute an HMAC-SHA256 of `${t}.${body}` with your endpoint's signing secret, using the raw request body, and compare it with v1 using a constant-time comparison. Reject requests whose timestamp is more than a few minutes old.

const expected = crypto.createHmac("sha256", secret)
  .update(`${t}.${rawBody}`).digest("hex");

Best practices

• Return a 2xx response quickly, then process asynchronously.
• Use the x-platform-event-id header to ignore duplicate deliveries.
• Failed deliveries are retried with backoff; make your handler idempotent.
• Use separate endpoints and secrets for sandbox and live.