Webhook contract
Keep every downstream system updated when an agent-driven checkout creates or changes an order.
Order-lifecycle events emitted by UCP transactions — reusing Aly's general webhook delivery pipeline.
UCP doesn't define its own webhook channel — it reuses Aly's general webhook system. After you create a checkout session or an order via UCP, the same delivery pipeline that powers the merchant dashboard fires events to any endpoints you've registered.
This page describes the events relevant to a UCP integration. For endpoint registration, signing, retries, and replay, see the Webhooks section.
UCP-related events
| Event | When |
|---|---|
checkout_session.created | A new session was created (UCP or hosted checkout). |
checkout_session.updated | Line items, address, shipping option, or discount changed. |
checkout_session.completed | Payment captured; order_id is populated. |
checkout_session.expired | Session passed its TTL without completing. |
checkout_session.cancelled | Cancelled by buyer or system. |
order.created | Order persisted after a successful checkout. |
order.fulfilled | Merchant marked an order as fulfilled (carrier + tracking). |
order.refunded | Full or partial refund processed. |
order.return_requested | Buyer initiated a return. |
order.exchange_requested | Buyer initiated an exchange. |
Payload shape
{ "id": "evt_8a1...e7c", "type": "checkout_session.completed", "created_at": "2026-05-19T08:35:14.000Z", "site_slug": "acme", "data": { "checkout_session": { "id": "cs_8f...e2", "status": "completed", "currency": "USD", "totals": { "subtotal": 4200, "shipping": 500, "tax": 376, "discount": 0, "total": 5076 }, "order_id": "ord_72...4b" } }, "ucp_agent": "agent-vendor/1.4"}When the originating request was signed (see Signed intents), Aly records the agent's identity and exposes a short ucp_agent marker on the event so downstream consumers can branch.
Delivery contract
- Transport: HTTPS POST, JSON body.
- Signing:
X-Aly-Signatureheader with an HMAC-SHA256 of the body using your endpoint secret. See HMAC signature verification. - Retries: Exponential backoff over ~72 hours on any non-2xx response. Audit trail in Delivery + replay.
- Ordering: Not guaranteed. Use
created_at+ the resourceidto reconcile.
event.id and short-circuit duplicates.Order lookup
For polling alternatives, agents can hit GET /api/ucp/v1/orders/{id} directly. The shape is the same as the order field on a completed checkout session, plus fulfillment state and shipment records.
Was this page helpful?