Skip to main content

Register a Webhook

For the other webhook endpoints, see the Webhooks API reference.
The full signing secret is returned only at creation time. Store it immediately - it is masked on all subsequent calls. If lost, rotate the secret to get a new one.

Supported Events

transfer.completed fires at initiation with status PROCESSING - not at final settlement. Always subscribe to payment.completed and payment.failed for the definitive outcome.

Delivery Headers

Bila attempts delivery 7 times: immediately, then after approximately 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours and 24 hours. Each delay is jittered by ±20%. The delivery is marked FAILED only after the seventh attempt fails. Return HTTP 200 in under 10 seconds and process asynchronously.

Verify Signatures

Read the raw request body as a string before JSON parsing - the signature is computed against the raw bytes. Parsing first will break verification.

Pre-Launch Checklist

  • Webhook registered and signing secret stored
  • Signature verification implemented and tested
  • payment.completed and payment.failed received correctly
  • Duplicate delivery detection via X-Bila-Delivery working
  • Endpoint returns 200 in under 10 seconds