Events API
The Decal event system — event naming conventions, the common event envelope, and the catalog of available events grouped by namespace.
Decal fires events whenever something significant happens — a payment is received, a session expires, an order changes state. Each event carries a structured payload describing what happened.
Events are channel-agnostic: the same event object is delivered whether you're using webhooks today or other delivery channels in the future. See Webhooks for HTTP delivery setup.
Event naming
Events follow a dotted-namespace convention:
{resource}.{subresource}.{action}For example, checkout.session.completed belongs to the checkout.session.* namespace — all
events that fire on checkout session state changes. This grouping means you can match a family of
events with a single prefix check.
Event object
Every event shares a common envelope:
| Field | Type | Description |
|---|---|---|
event | string | The event type name. |
createdAt | DateTime | When the event was created (UTC). |
Additional fields depend on the event type. Use the event field to determine which data is
present. Each namespace page (linked below) documents the additional fields for its events.
Event catalog
Click through to a namespace for the payload schema and example payloads.
Delivery channels
Events are currently delivered via webhooks — HTTP POST requests to a URL you provide. See Webhooks for setup, handling examples, and delivery semantics.
Additional delivery channels (event streaming, polling via GET /v0/events, etc.) will be
documented here as they become available.