Handling Webhook Deliveries

Respond quickly, with a 2xx

Your endpoint must respond with a 2xx status. Anything else — a 4xx, a 5xx, or your server timing out — is treated as a failure and queued for retry.

Respond as soon as you’ve durably recorded the event; do the actual work (updating an order, sending a confirmation email) after responding, or in a background job. A slow handler that takes too long to respond risks being retried even though it would have eventually succeeded.

Retries

A failed delivery is retried with exponential backoff — starting at 1 minute, doubling each time, capped at 1 hour — until it succeeds. There’s no fixed number of attempts where Baiyar gives up; it keeps retrying at the 1-hour interval indefinitely until your endpoint returns a 2xx.

Make your handler idempotent

Because of retries, your endpoint will receive the same event more than once in normal operation — not just as an edge case. Use the event’s id to deduplicate: record which IDs you’ve already processed, and skip (while still responding 2xx) if you see one again.

Caution

Don’t rely on data.id (the transaction/payment ID) for deduplication — a resubmitted attempt after payment.failed can produce a new transaction, but the retried delivery of the same event always carries the same event id.

Testing before you go live

Use the sandbox payment simulator to trigger payment.paid / payment.failed deliveries end to end, without a real bank/QRIS provider — either from the Sandbox simulation tools on a checkout page (see Payment Links), or directly via POST /sandbox/payments/{providerPaymentID}/simulate. This is the fastest way to confirm your endpoint responds 2xx and your signature verification passes, before a real customer payment depends on it.

Next steps

Verifying Webhook Signatures — confirm a request genuinely came from Baiyar before you act on it.