Skip to content
Merchant guide
HTTPS · Signed events

Webhooks. Know when things change.

YallaBuy Webhooks push signed notifications to your server the moment any business event happens in your store. This page explains the model from the ground up: exactly what happens, how it differs from polling the API, and what you can build on top.

Reviewed against implementation
YOUR INTEGRATION, AT A GLANCE
Webhook delivery · Headers
POST /your-webhook-endpoint
Content-Type: application/json
webhook-event-type: order.created
webhook-id: <endpoint_id>
webhook-event-id: <event_id>
webhook-delivery-id: <delivery_id>
webhook-timestamp: <unix_seconds>
webhook-signature: v1=<hmac_sha256_hex>
See the implementation
On this page

01The event-driven model

YallaBuy Webhooks push real-time notifications to your server the moment a business event happens: a new order, an order status change, a return or refund, a product created/updated/deleted, an inventory movement, a redeemed coupon, a kitchen status change, or a closed register shift. Each notification is a single POST request carrying a signed JSON body, delivered to the HTTPS URL you register in the dashboard.

Instead of polling continuously, subscribe an endpoint and receive signed JSON POST requests. A delivery worker sends notifications; delivery can be delayed or duplicated, so build your receiver accordingly.

02What happens when an event occurs?

Supported operations record the event with the business transaction and schedule delivery to active subscribed endpoints. Recording an event does not prove receipt; inspect delivery status and attempts in the dashboard.

  • The event is stored with a unique identity and a copy of its payload (64 KB cap).
  • The delivery worker claims due deliveries in batches of up to 25; a periodic sweep picks up pending retries. This does not guarantee a fixed delivery latency.
  • Each delivery is sent as a signed POST request to your URL — any 2xx response settles it as successful.
  • Any failure is retried automatically on an exponential backoff schedule until it succeeds or exhausts its attempts.
  • Everything is recorded: events for 14 days, deliveries and attempts for 30 days — all visible on the webhooks screen.

03Webhooks versus API polling

The Public API returns data when you ask for it — look up an order by its id, for example. Webhooks push the news to you the moment it happens. The canonical integration uses both: the webhook tells you "a new order exists" in real time, and the Public API fetches any extra details you need or runs periodic compensating syncs for safety.

04Typical use cases

The platform provides the events and the signed delivery — the application itself lives on your side. These are examples of what gets built on top:

  • Sync new orders into an external fulfillment or accounting system the moment they are placed.
  • Update external stock immediately on any receipt, adjustment or damage movement.
  • Alert an external app or team on new cancellation requests, returns or refunds.
  • Feed automation platforms (such as n8n or any HTTP receiver) with a signed event stream.