Skip to content
DevelopersBuild with YallaBuy
Merchant guide
HTTPS · Signed events

The payload envelope and event shapes

Every event carries a unified envelope that reaches you identically in the payload and in the delivery headers. This page covers the envelope, the two shapes you may receive depending on event age, and the fixed size rules.

Start building
Reviewed against implementation
YOUR INTEGRATION, AT A GLANCE
Webhook delivery · Headers
POST /your-webhook-endpoint
Content-Type: application/json
webhook-event-type: order.created
webhook-id: <endpoint_id>
webhook-event-id: <event_id>
webhook-delivery-id: <delivery_id>
webhook-timestamp: <unix_seconds>
webhook-signature: v1=<hmac_sha256_hex>
See the implementation
On this page

01The unified envelope

KeyPresent onMeaning
idEvery eventThe textual event identity (same value as the webhook-event-id header) — e.g. mwh:order-created:<tenant>:<order>.
typeEvery eventThe event type (same value as the webhook-event-type header).
api_versionEvery eventThe payload schema version — currently v2.
tenant_idEvery eventThe UUID of the store owning the event.

02The two shapes by event age

First-generation events (order.created, order.status_changed, return.created) kept all of their original flat fields with the envelope added at the same level — no old key was ever removed, so pre-existing consumers keep working unchanged. V2 events (every newer type) ship {id, type, api_version, tenant_id, data} — the whole event lives inside the data object, and the data keys for each type are exactly the ones shown in its example on its page; nothing else is ever added.

03Fixed size rules

  • The whole payload is bounded at 64 KB.
  • The items array is capped at the first 100 entries with items_truncated = true (on order and return events).
  • The variants array on product events is capped at 100 with variants_truncated = true.
  • Free-text fields such as reason and notes are sent truncated at 500 characters (product descriptions at 1000).
  • Amounts are numbers in the store currency; timestamps are ISO 8601.

Keep exploring

Event catalog — the 17 typesReceiving events — headers and response rulesorder.created — first-generation event (flat fields + envelope)

COMPLETE YOUR INTEGRATION