Set up and verify webhooks
Receive event notifications and verify the signature before you trust the payload.
Last updated June 1, 2026
Webhooks notify your server when payment events happen, so you don't have to poll constantly.
Verify every webhook
Each webhook delivery includes an X-Boldswitch-Signature header. It contains an HMAC-SHA256 of the raw request body, computed with your webhook secret.
Before you process any webhook:
- Read the raw, unparsed request body.
- Compute an HMAC-SHA256 of that body with your webhook secret.
- Compare it to the X-Boldswitch-Signature header using a constant-time comparison.
- Reject any request with a missing or mismatched signature.
Retries
We retry failed deliveries with exponential backoff for up to 24 hours. Return a 2xx status quickly to acknowledge receipt, and do slow work asynchronously.
Tip: Verify the signature against the exact bytes you received. Re-serialising the JSON first can change the body and break verification.
Reconcile as a backstop
Even with webhooks, you can confirm a payment server-side with GET /api/v1/payment/status/:ref before fulfilling an order. If a webhook is delayed, polling status keeps you accurate.
What's next
- Not arriving? See A webhook wasn't delivered.
- See Payment statuses and error codes.