Webhooks overview
Send important Aly events to your systems the moment orders, checkouts, products, or memberships change.
Event push from Aly to your HTTPS endpoint — HMAC signing, retries, audit log, replay.
Webhooks push events from Aly to your HTTPS endpoint as they happen — orders created, fulfilled, refunded; checkout sessions completed; subscriptions started or cancelled. Each delivery is signed and logged; failures retry with exponential backoff.
At a glance
| Transport | HTTPS POST, JSON body. |
| Signing | HMAC-SHA256 with your endpoint secret, in X-Aly-Signature. |
| Retries | Exponential backoff over ~72 hours on any non-2xx. |
| Ordering | Best-effort, not guaranteed. Dedupe and reconcile on receive. |
| Register via | Dashboard, REST /merchant/webhooks, MCP webhooks.endpoints.create, or CLI. |
Anatomy of a delivery
http
POST /aly/webhooks HTTP/1.1Host: my-app.exampleContent-Type: application/jsonX-Aly-Delivery-Id: del_3f...X-Aly-Event-Id: evt_8a1...X-Aly-Event-Type: order.fulfilledX-Aly-Timestamp: 1748112900X-Aly-Signature: t=1748112900,v1=4f3c... { "id": "evt_8a1...e7c", "type": "order.fulfilled", "created_at": "2026-05-19T08:35:14.000Z", "site_slug": "acme", "data": { ... }}What you implement
- Verify
X-Aly-Signaturewith the endpoint secret. See HMAC signature verification. - Acknowledge with a
2xxwithin 5 seconds. Slow handlers are retried. - Dedupe on
event.id— replays and retries reuse the same id. - Process. Failures should return non-2xx so Aly retries.
Acknowledge fast, process slow
Spend your 5 seconds verifying + enqueueing, not processing. Drop the event onto a queue or background job and return 200 immediately. Long-running work blocks Aly's retry loop and burns timeouts.
Next steps
- Event types — the catalog of events you can subscribe to.
- Registering endpoints — dashboard, REST, MCP, CLI.
- HMAC signature verification — exact construction and verify code.
- Delivery + replay — retries, audit log, replay endpoint.
Was this page helpful?