Skip to main content
Webhooks push signed HTTP callbacks to your server when events happen in your account — payments, paywall and service changes. Verify each request with the 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

Verify X-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):
  1. Extract the timestamp and signature from the header. Split on ,, then =. t is the unix-seconds timestamp. v1 is the hex HMAC. Ignore any other schemes.
  2. Prepare the signed payload. Concatenate: timestamp (as a string) + . + the raw JSON body (exact POST bytes as utf8).
  3. Compute the expected signature. HMAC-SHA256 of that string, using the full whsec_… secret as the key. Encoding is lowercase hex.
  4. 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 a 2xx 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 2xx after 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.