Webhooks
EYalla emits webhooks on tenant lifecycle and customer-facing events. Subscribe by configuring an endpoint URL in your developer dashboard (Coming Soon). All payloads are JSON, signed via HMAC SHA256 in the X-EYalla-Signature header.
Event types
| 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} |
tenant.created |
New tenant provisioned | {tenant: {id, subdomain, plan_slug, ...}} |
tenant:{id}:created |
tenant.suspended |
Hub admin suspends a tenant | {tenant: {id, reason}} |
tenant:{id}:suspended:{at} |
subscription.cancelled |
Subscription canceled (immediate or period-end) | {subscription: {...}, immediate: bool, reason} |
sub:{id}:cancelled |
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.
Idempotency
Every event carries an idempotency_key. Your handler should look it up against a dedup store before processing — if you've seen it before, return 200 immediately. Otherwise process + record. The platform retries failed webhooks (non-2xx response) up to 5 times with exponential backoff.
Replay
Failed events show up in your dashboard with a "Replay" button. Useful when you ship a bug fix and want to backfill the events your buggy handler missed.
Coming soon
- Filtered subscriptions (subscribe only to
order.paidfor a specific gateway, etc.) - Webhook signing secret rotation
- Per-environment endpoints (staging vs. production)