Webhooks
Developers → Webhooks is where you tell us which URL to notify when something happens, and where you find out whether we have been able to.
This page is the operational side. The verification code your developer needs is in Webhooks (API).
Registering an endpoint
Section titled “Registering an endpoint”Register it in the environment it serves — test and live endpoints are separate records with separate signing secrets. Going live means registering your production URL again, not flipping a switch on the test one.
Your URL must be HTTPS and publicly routable. Loopback and private addresses are refused, because our delivery workers run inside our own network and could not reach them. For local development, use a tunnel and register the tunnel URL as a test endpoint.
Subscribe to what you use
Section titled “Subscribe to what you use”Pick the specific event types you handle. The alternative — subscribing to everything — costs you a delivery and us a retry for every event you were going to ignore anyway, and it makes your failure counters meaningless.
Most integrations need:
transaction.succeeded,transaction.failed,transaction.expiredrefund.succeeded,refund.failedif you refundpayout.succeeded,payout.failedif you pay outdispute.opened,dispute.evidence_required— these have a deadline attached; see Disputessettlement.paidif you reconcile automatically
Timeout and attempts
Section titled “Timeout and attempts”Two settings per endpoint:
- Timeout (default 10 seconds). We count a slower response as a failed attempt.
- Max attempts (default 8). After that we abandon the event.
Raising the timeout is almost never the right fix for a slow handler. The right fix is for the handler to verify the signature, put the event on a queue and return — the work happens after you have answered us. A handler that updates three tables inline will eventually exceed any timeout you set.
Health, and what the numbers mean
Section titled “Health, and what the numbers mean”Each endpoint shows its own health: consecutive failures, the last success, the last failure and its reason.
Watch the consecutive failure count. After repeated failures we stop delivering
to the endpoint entirely and set auto_disabled_at. At that point events are no
longer attempted, and your system is not merely behind — it is not being told
anything at all.
To recover: fix the endpoint, then set its status back to active. That also clears the failure streak. Then backfill what you missed — see below.
The failure reason is worth reading rather than guessing at. A timeout, a TLS
failure, a 500 from your side and a DNS failure are four different problems, and
only one of them is about your code.
Recovering missed events
Section titled “Recovering missed events”Do not go looking for a way to re-send everything. There are two tools, for two situations:
One delivery, again — useful while your developer is iterating on signature verification. Open the delivery and replay it. It is signed freshly and arrives like any other.
Everything you missed — your developer reads the event log
(GET /v1/events?after_sequence=…). Every delivery carries a sequence that is
monotonic for your account, so the highest one you have processed tells you exactly
where to resume. Reading the log sends nothing, so you recover at your own pace
instead of your handler being hit by a burst of replays.
That is why the API page tells your developer to record the highest sequence they have processed. Without it, “what did we miss” has no precise answer.
Rotating a signing secret
Section titled “Rotating a signing secret”Rotation gives you a new secret and an overlap window. During the window we sign each delivery with both the new and the old secret, and either verifies — so a part-deployed rotation does not drop events.
Your handler has to accept any of the signatures in the header for this to work, which is a one-line property of the verification code and is covered in the API page. If your handler assumes a single signature, rotation will break it, and you will find out during the rotation.
Rotate if the secret has been anywhere it should not have been. After rotation, the old secret stops working at the end of the window.
Why your handler must tolerate duplicates
Section titled “Why your handler must tolerate duplicates”Delivery is at-least-once and always will be. An endpoint that times out after processing a request has to be retried, because the alternative is dropping an event about money.
Every delivery carries a stable event id that does not change between retries. Deduplicate on it. If your system can process the same event twice and double a record, it will.