Webhooks

Register an endpoint

Nothing is sent until you tell us where. Add an endpoint in the dashboard under Developers → Webhooks, or from your code:

const endpoint = await sp.webhookEndpoints.create({
  url: "https://example.com/webhooks/secure-processing",
  enabled_events: ["payment_intent.succeeded", "refund.succeeded"], // omit for every event
});

endpoint.secret; // "whsec_..." — store it now; it is never shown again

Then prove the wiring before a real payment depends on it: sp.webhookEndpoints.sendTest(endpoint.id) sends a webhook_endpoint.test event to that endpoint and no other.

Verify every one

const event = await sp.webhooks.constructEvent(
  rawBody,
  request.headers.get("Secure-Processing-Signature")!,
  process.env.SECURE_PROCESSING_WEBHOOK_SECRET!,
);

The signature header looks like t=1740000000,v1=abc123…: a Unix timestamp and a hex HMAC-SHA256, keyed with your secret, of the timestamp, a full stop and the raw body. During a secret rotation there is one v1 value per secret still in force — two, or more if you rotate again inside the window — and a match on any of them is a pass. The timestamp is part of what was signed, so an old request cannot be replayed at you — constructEvent rejects anything more than five minutes from your clock. Change that with its fourth argument, { toleranceSeconds: 600 }, if your server’s clock is not kept in sync.

What arrives

A POST with a JSON body that is an event object, the same one GET /v1/events/:id returns:

{
  "id": "evt_4gH6jK8lM0nP2qR4sT6uV8wX",
  "object": "event",
  "type": "payment_intent.succeeded",
  "api_version": "2026-09-01",
  "account": "acct_1aB2cD3eF4gH5iJ6kL7mN8oP",
  "livemode": false,
  "created": 1761868800,
  "data": {
    "object": { "id": "pi_3KqL8xQpR2sT7vW9yZ1aB4cD", "object": "payment_intent", "status": "succeeded", "...": "..." }
  }
}

account is the account it happened on. data.object is the payment, refund, payout or other object the event is about, as it stood when the event happened; its own object field says which. id is the same on every retry and every resend of the event, which is what makes it the key to deduplicate on. The request also carries Secure-Processing-Event-Id, Secure-Processing-Event-Type and Secure-Processing-Delivery-Id headers, for routing before you parse anything — but verify the signature before you trust any of it.

The events

A platform's Connect endpoint is told about its connected accounts only while it may still reach them. An event waiting to be sent is dropped if the account is rejected or moves to another platform first, and sending one again is refused. While a platform is paused its events wait, and they go once it is active again. It also reads less than the account does: an application's decision, an adjustment's reason, a payout's failure reason and a dispute's outcome note stay with the account.

Retries

Any response outside the 2xx range is a failure and we try again: after 30 seconds, then 2 minutes, 10 minutes, 30 minutes, an hour, and on out to about 35 hours in total. In test mode the retries stop after about five hours, at the 3-hour step. Answer 200 as soon as you have stored the event and do the work afterwards — a slow handler becomes a timeout, and a timeout becomes a retry.

Delivery is at-least-once, so handle events idempotently: key on event.id and ignore one you have already processed. Events can also arrive out of order, so when the order matters, retrieve the object by id rather than assuming a sequence. Events caused by the same change carry the same created and have no order between them at all — the payment that settles an invoice fires invoice.payment_succeeded and invoice.paid alongside each other, and either may come first, in the events list or at your endpoint.

An endpoint whose deliveries keep failing until their retries run out — twenty in a row — is switched off, and you get webhook_endpoint.disabled at any other endpoint you have. Disabling one yourself is DELETE /v1/webhook_endpoints/:id, or sp.webhookEndpoints.disable(id): despite the method, the endpoint is not deleted. It stops receiving events, stays in the list with status: "disabled", and its delivery history stays readable.

Switch a disabled endpoint back on — whichever of us disabled it — with Enable endpoint on its dashboard page, or:

curl https://api.secureprocessing.app/v1/webhook_endpoints/we_6mN8pQ0rS2tU4vW6xY8zA0bC \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "disabled": false }'

It keeps its id and its secret, and its failure count starts again from zero. Nothing is resent by itself, and what you have to do depends on when: events that happened while it was off were never queued for it — catch up from the events list, as below. A retry that came due while it was off was abandoned; it is in the delivery log, and Send again resends it. A retry scheduled for after you switch it back on is still delivered.

Rotating a secret

Rotating gives you a new secret and keeps the old one working for a window you choose: up to 24 hours, 12 if you leave it out, or 0 to retire the old one at once. We sign with both during the overlap, so you can deploy the change without dropping events.

const endpoint = await sp.webhookEndpoints.rotateSecret(id, {
  expires_in_hours: 12,
});
// endpoint.secret is the new one, shown once

If you miss some

Every event is readable from the API, and an event you missed is the same event a retry would have delivered. After an outage, collect everything newer than the last event you processed and handle it oldest first, rather than waiting for retries. The list is newest first, so that means paging back from the newest until you reach the one you had:

async function eventsSince(lastHandledId: string) {
  const missed = [];
  let cursor: string | undefined;
  for (;;) {
    const page = await sp.events.list({ limit: 100, starting_after: cursor });
    for (const event of page.data) {
      if (event.id === lastHandledId) return missed.reverse(); // oldest first
      missed.push(event);
    }
    if (!page.has_more) return missed.reverse();
    cursor = page.data[page.data.length - 1].id;
  }
}

for (const event of await eventsSince(lastHandledId)) await handle(event);