Skip to content
Baiyar Docs

How Webhooks Work

Push, not pull

Section titled “Push, not pull”

Without webhooks, the only way to know a payment finished is to poll GET /v1/payments/{paymentID} on a loop. A webhook flips that: Baiyar makes an HTTP POST request to a URL you configure, carrying the outcome, the moment the payment reaches a final state. Your server just needs an endpoint that accepts that request — no loop, no wasted requests while a payment is still pending.

The delivery lifecycle

Section titled “The delivery lifecycle”
  1. A transaction reaches a final state — succeeded, failed, or expired. (pending and processing never trigger a webhook; see Payment Statuses for what each status means.)
  2. Baiyar queues one event for that transaction — payment.paid for succeeded, payment.failed for failed or expired.
  3. A background delivery worker picks up queued events roughly every 5 seconds, signs the payload, and sends it to your configured URL as an HTTP POST with a Content-Type: application/json body.
  4. Your endpoint responds. A 2xx status marks the event delivered. Anything else — including a timeout — is treated as a failure and retried; see Handling Webhook Deliveries.

This means delivery is asynchronous and eventually-consistent, not instant — expect it to typically land within a few seconds of the payment finishing, not the same millisecond.

The same queue-sign-retry mechanics apply to project and API key changes too — see Project and API Key events for those payload shapes.

What you get, and what you don’t

Section titled “What you get, and what you don’t”

The event payload is a summary (id, reference, amount, status, timestamps) — not the full payment object. If you need something not in the payload (fee breakdown, customer info, payment instructions), call GET /v1/payments/{data.id} with your API key using the ID from the event. See payment.paid or payment.failed for the exact payload shape.

Next steps

Section titled “Next steps”