Browse wiki · Payment webhooks

Payment webhooks

Confirm payment on your server

Keep your catalog and fulfillment in your own system. Save the invoice ID with your order ID. A browser redirect, submitted transaction does not prove payment. On payment_intent.succeeded, retrieve the server-side receipt with a payments:read key and match the amount, USDC currency, recipient, invoice and order before fulfilling.

Configure and verify

Open API → Payment webhooks. Configure a public HTTPS endpoint on port 443 and keep its signing secret on your server. The primary endpoint uses GET/PUT /webhook. Webhook Pro can use additional endpoints under /webhooks, each with a separate secret and optional event filters.

  1. Read at most 64 KiB of the exact raw request body before JSON parsing.
  2. Reject malformed X-Payment-Timestamp values and timestamps more than five minutes old or more than five minutes in the future.
  3. Compute HMAC-SHA256 over timestamp + "." + rawBody, and compare the v1= hex signature in constant time. For Pro, select the configured secret by X-Payment-Webhook-ID.
  4. Compare X-Payment-Event-ID to the ID in the signed JSON body. Reject mismatches and unsafe numeric IDs.
  5. In one database transaction, insert a unique workspace + event ID into a durable inbox or job table and acknowledge with 2xx. The worker must verify the receipt and commit order fulfillment idempotently. Never treat a processed marker alone as fulfillment.

Webhooks are delivered at least once. A lost acknowledgement, automatic retry or manual replay can repeat an event. A retry has a new timestamp and signature but keeps the event ID. Never log signing secrets or unredacted bodies. Download Node.js verification, Python verification, a bounded Python receiver with SQLite inbox, and setup instructions.

Test your receiver

Use Send test event in the API tab or POST /webhook/test; Pro uses POST /webhooks/{id}/test. Both send a signed body with a unique string test_ ID, type: "webhook.test", test: true, and createdAt. The event ID header equals the body ID. Pro also sends the endpoint ID header. Acknowledge these tests without fulfilling an order. The primary endpoint allows one test per workspace per minute; Pro allows one per endpoint per minute. The response reports HTTP status, safe error code, duration and delivery outcome. The primary test returns HTTP 200 with diagnostics even when delivery fails; a Pro test failure returns HTTP 409.

Diagnose, replay and recover

Only a 2xx receiver response acknowledges delivery. Redirects are not followed. Endpoint health includes last success, pending and failed counts, oldest pending time, and a safe error code. Pro also shows dead-letter count and the last test outcome. Pro delivery pages are newest first, have a limit of 1–100, and scan at most 1,000 records per page. Filter by status, event ID and event type, then follow nextCursor. Open a delivery to inspect up to 16 chronological attempts and latency. Automatic retries stop after 12 attempts or 72 hours and leave a dead_letter record. Manual replay is limited to one per event per minute and 100 per endpoint per UTC day. After fixing the receiver, retry a retained failed delivery. Some retries may already be in flight, so your receiver must remain idempotent.

Pause retains queued deliveries while you repair a receiver. Deleting an endpoint with unresolved deliveries requires explicit confirmation: reconcile receipts first. The API returns pending_deliveries_require_acknowledgment; only a DELETE body containing {"acknowledgePendingLoss":true} discards that queue and history, with an audit record. Payment receipts remain. An already in-flight request can still finish after pause, rotation or deletion.

If rotationRequired appears, the stored Pro signing key is missing. Rotate the endpoint secret, securely install the newly returned key at your receiver, send a test, and enable delivery. Rotation pauses the endpoint; never accept unsigned requests or signatures made with an empty key. Reconcile the free /changes feed with /receipts when an event is no longer retained. If a change cursor expires, reconcile retained receipts before using its restart cursor. Keep your own accounting records because server retention is finite.

← All topics