X-Webhook-Signature header. Your backend can grant access, update a ledger, or alert your team without polling Transactions or Events.
Webhooks are configured from the dashboard only. There is no API to create or manage endpoints.
Add an endpoint
In the dashboard, open Webhooks and click Add endpoint:
You can configure up to 20 endpoints. Each endpoint can subscribe to a different set of events.
Events
Choose which events each endpoint receives:Webhook
payment.* names follow transaction state (Pending / Completed / Failed). They are not the dashboard Events REQUEST / SUCCESS / ERROR stream, and GET /v1/events is not a webhook payload.Verify each delivery
VerifyX-Webhook-Signature with the endpoint’s full whsec_ secret before you grant access or update a ledger. Each endpoint has its own secret, shown in the endpoint list. Store it server-side.
Pass the raw POST body, the
X-Webhook-Signature header, and the endpoint secret into verifyProceedsWebhook (or the Python equivalent).
Proceeds signs the raw request body. If your framework parses JSON first (
express.json(), req.json(), and similar), verification fails. Use the unparsed bytes. The HMAC key is the full whsec_… secret — do not strip the prefix.Verify manually
Use these steps if you are not pasting the snippet above. Proceeds sends a signature header like this (shown with newlines for clarity; the real header is one line):- Extract the timestamp and signature from the header. Split on
,, then=.tis the unix-seconds timestamp.v1is the hex HMAC. Ignore any other schemes. - Prepare the signed payload. Concatenate: timestamp (as a string) +
.+ the raw JSON body (exact POST bytes as utf8). - Compute the expected signature. HMAC-SHA256 of that string, using the full
whsec_…secret as the key. Encoding is lowercase hex. - Compare. Constant-time compare (
timingSafeEqual/hmac.compare_digest) of the hex-decoded buffers. Reject on mismatch or a malformed header.
There is no timestamp skew or replay window in Proceeds today. Do not implement a fake 5-minute check. Dedupe on envelope
id.Delivery and retries
Proceeds expects a2xx within 10 seconds. Non-2xx responses retry up to 3 attempts, with backoff 2s / 4s / 8s. Retryable status codes: 408, 429, 5xx. Other 4xx responses are not retried.
Open an endpoint’s Recent deliveries to inspect history:
Manage endpoints
The Webhooks list shows each endpoint’s Status (active or paused), subscribed Events, Last delivery, and signing Secret. From there you can pause, edit, or delete an endpoint.Best practices
- Return
2xxafter verify and de-dupe; process asynchronously (10s timeout). - De-dupe on envelope
id. - Subscribe narrowly — only enable the events each endpoint needs.
Transactions
The payment state that
payment.* events mirror.Events
The request lifecycle you can also inspect in the dashboard.

