Webhooks

Ewity POSTs webhooks to endpoints you register on your application's
Webhooks tab in the Developer Portal, so
your platform finds out about merchant-side activity without having to poll
GET /orders/{id} or the catalogue endpoints.

This page covers webhooks from an online ordering platform's
perspective. The full delivery contract — the signed envelope, endpoint
management, and the complete event catalog across the whole business —
lives in Webhooks for Apps. Per-event request and
response shapes are in the API reference sidebar.

Endpoints & subscriptions

Register any number of webhook endpoints, each subscribed to exactly the
events it wants — one endpoint for order events and another for catalogue
sync, or a single endpoint for everything. Add, edit and delete endpoints on
the Webhooks tab; changes take effect immediately.

New endpoints receive the signed envelope format:

X-Ewity-Event: order.status_changed
X-Ewity-Delivery: evt_9f2c1a7d3b8e
X-Ewity-Signature: t=1786575678,v1=5f8a…c41d

{
  "id": "evt_9f2c1a7d3b8e",
  "event": "order.status_changed",
  "created_at": "2026-08-12T14:03:22+05:00",
  "company": { "id": 1, "name": "Test Company", "domain": "test" },
  "install": { "store_id": "pl_id_…", "external_account_id": "acc_42" },
  "data": { "…": "the order payload" }
}

Verify X-Ewity-Signature with your signing secret (see
Webhooks for Apps for the exact scheme and sample
code), dedupe on the envelope id, and acknowledge with any 2xx inside a
few seconds.

The ordering events

Event	What it means
`order.status_changed`	The order's `status` changed — covers merchant acceptance (when the bill is generated and `POST /orders/{id}/payment` becomes callable), all forward transitions, cancellations, and the merchant-driven "review requested" flow. The event you'll handle most often.
`store.turned_on`	A previously offline online location is back. Re-enable it on your side and re-sync the catalogue if you'd skipped it.
`order.notification`	A customer-facing message about an order on your platform (e.g. "your order is on its way"). Forward `title` / `message` to your own SMS / push / email channel.
`order.review_reminder`	A reminder that an order is stuck in `review-requested` and the customer hasn't acted on the merchant's edits yet. Nudge the customer.
`catalogue.updated`	One or more `(online_location_id, product_id, variant_id)` triples may have changed — stock crossing in/out of "in stock", catalogue toggles, bulk CSV imports. Refetch via `POST /locations/{id}/catalogue/lookup`.

There is no webhook on order creation. When your platform calls
Create Order the response is the order — no OrderCreated event
fires afterwards. Webhooks cover what happens on the merchant side after
that: acceptance, status changes, store availability, etc.

There is also no store.turned_off event today — fall back to polling
GET /stores if you need to detect a store going offline.

Recommended catalogue-sync flow

If an endpoint subscribes to catalogue.updated, this is the prescribed flow
to keep your local catalogue cache in sync:

Receive a catalogue.updated delivery.
Group data.items[].variant_id by online_location_id.
For each (online_location_id, variant_ids) group, call
POST /locations/{online_location_id}/catalogue/lookup
with {variant_ids}.
Upsert each returned product (and its nested variants) into your local
catalogue cache. Variants you asked for that don't appear in the response
have been removed — delete them from your cache.

Bulk operations on the merchant side (CSV imports, stocktakes) coalesce into
a single delivery with a long items array, so you won't be flooded with
hundreds of one-item deliveries.

Receiver checklist

Verify X-Ewity-Signature against your signing secret (constant-time
compare, reject deliveries older than 5 minutes). Reject failures
with 401.
Branch on X-Ewity-Event (or the envelope's event) to route to the
right handler.
Dedupe on the envelope id — delivery is at-least-once.
Acknowledge with 2xx quickly and process asynchronously on your side.
Tolerate fields you don't recognise — Ewity may add fields to payloads
without notice. Treat unknown fields as forward-compatible.
Have a way to replay missed events. If you suspect a delivery was
missed, fall back to GET /orders/{id} (orders) or GET /stores +
GET /locations/{id}/catalogue (storefronts) to reconcile state.

Integrated before the Apps release?

Platforms that registered the old webhook_url / inventory_webhook_url
fields were migrated automatically: those endpoints keep receiving the
classic unwrapped payloads under the legacy event names
(OrderStatusChanged, OrderNotification, StoreTurnedOn,
ReviewRequestedReminder, CatalogueUpdated) with the X-Event header and
your platform bearer token — byte-for-byte what they received before, no code
change needed. Each legacy event has a modern envelope twin carrying the
identical data payload; to upgrade, add a new endpoint subscribed to the
modern events and remove the legacy one when you're satisfied. Details in
Webhooks for Apps.