Webhooks

⚠️ Not available yet — do not build against this

EYalla does not currently send webhooks. Nothing calls your server. If you point a receiver at us today, it will never be called.

An Elite store can now register an endpoint in its admin, under Settings → Webhooks, and that screen says the same thing: we keep what you register and we send nothing to it. It exists so you can tell us the event list below is wrong before the delivery side is built, rather than after.

Everything below is the planned contract, published so you can design against it and tell us if it will not work for you. It is a specification, not a description of behaviour that exists. Treat every sentence as future tense.

Need events today? Poll the REST API — orders supports updated_since, which covers most of what a webhook would give you.

Once shipped, EYalla will emit webhooks on the store events listed below. The store owner subscribes by adding an endpoint URL under Settings → Webhooks in the store admin, which is where the signing secret is issued. All payloads will be JSON, signed via HMAC SHA256 in the X-EYalla-Signature header.

Planned event types

These are the events a store can subscribe to. The slugs are the wire contract and will not be translated or renamed.

Event	When	Payload	Idempotency key
`order.created`	Order row created (any source — storefront, POS, API)	`{order: {id, number, ...}, tenant: {...}}`	`order:{id}`
`order.paid`	Payment webhook confirms payment	`{order: {...}, gateway, transaction_id}`	`order:{id}:paid`
`order.payment_failed`	Gateway confirms terminal failure	`{order: {...}, gateway, error_code}`	`order:{id}:failed:{attempt}`
`order.refunded`	Refund completes (full or partial)	`{order: {...}, amount, currency, partial: bool}`	`order:{id}:refunded:{txn}`
`order.status_changed`	`fulfilment_status` flips (confirmed / processing / shipped / delivered / cancelled)	`{order: {...}, old_status, new_status, awb?, carrier?}`	`order:{id}:status:{new}`

Platform events — not sent to a store

tenant.created and tenant.suspended were listed here until 2026-08-26 and are not available to a store, by decision rather than omission: a merchant learning that their own store was suspended through a webhook is the wrong way round, and those two read as platform-partner events with a different audience. subscription.cancelled — the store's own EYalla subscription being cancelled — was withdrawn on 2026-09-11 for the same reason, before anything had been delivered for it. They are named here so an integrator who saw the earlier list knows where they went, not because they are coming.

Planned signature verification

$signature = $request->header('X-EYalla-Signature');
$expected = hash_hmac('sha256', $request->getContent(), $YOUR_WEBHOOK_SECRET);
if (! hash_equals($expected, $signature)) {
    abort(401, 'Bad signature');
}

Use hash_equals (timing-safe comparison) — === leaks signature byte-by-byte under load. This snippet is worth keeping whatever we ship; it is how you verify any HMAC-signed webhook.

Planned idempotency

Every event will carry an idempotency_key. Your handler should look it up against a dedup store before processing — if you have seen it before, return 200 immediately; otherwise process and record. A failed delivery (any non-2xx response) will be retried six times — 1 minute, 5 minutes, 30 minutes, 2 hours, 8 hours and 24 hours after the first attempt. After the last one the endpoint is switched off and the store is told, and the events it missed stay available to replay. The schedule spans a day rather than an hour on purpose: an overnight outage on your side should cost you nothing.

Planned replay

Failed events will appear in your dashboard with a "Replay" button, for backfilling the events a buggy handler missed after you ship a fix.

Also planned, after the above

Filtered subscriptions (subscribe only to order.paid for a specific gateway, etc.)
Webhook signing secret rotation
Per-environment endpoints (staging vs. production)

What exists today

Webhook events we receive — payment-gateway callbacks into EYalla — are recorded and visible to platform staff, and that is what the Webhook Events console shows. It is inbound only. Nothing on this page is wired to it.