Webhooks

title: "Webhooks" description: "Signed event notifications you can rely on. Retried for 30 days with exponential backoff." section: "Concepts" order: 4 updated: "2026-04-18" sourcePath: "content/docs/concepts/webhooks.mdx"

BchainPay POSTs signed JSON events to a URL you configure. Use them to fulfill orders, reconcile ledgers, and trigger downstream automation. Webhooks are an optimization — the API is always the source of truth.

Delivery guarantees

• At-least-once. A successful 2xx response acknowledges delivery.
• 30-day retry queue with exponential backoff and jitter. Failed deliveries are surfaced in the dashboard.
• Per-merchant signing secret on every event. See Verify a webhook.
• Replay protection via the t= timestamp. Reject anything older than 5 minutes.

Idempotency on your side

We may deliver the same event more than once. Use the id field on the event envelope as a deduplication key.

Configuring an endpoint

Add an HTTPS endpoint in the dashboard, choose the events you want, and copy the per-endpoint signing secret. You can subscribe to specific event types or to all events.