Skip to main content

Register a Webhook

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

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

Delivery Headers

Bila retries up to 3 times on failure (~5s, ~10s, ~20s). Return HTTP 200 immediately 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