Webhooks

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

Per-event request and response shapes live in the API reference,
under the Webhooks section in the sidebar. This page covers the
common stuff: delivery semantics, what each event means, and the
receiver checklist.

Two webhook URLs

You can register two separate webhook URLs, each opt-in:

Both URLs use the same auth (Authorization: Bearer YOUR_PLATFORM_AUTH_TOKEN).
Setting the inventory URL is optional — if you don't need to track stock or
catalogue changes from the merchant side, leave it null and you won't receive
those events.

Delivery

• Method: POST
• Content-Type: application/json
• Body: the event payload itself — there is no data: envelope.
• Headers Ewity sets:

  Authorization: Bearer YOUR_PLATFORM_AUTH_TOKEN
  X-Event: OrderStatusChanged
  Content-Type: application/json

  • Authorization carries the same bearer token your platform uses to
    call the API. Validate it server-side and reject anything that
    doesn't match — that's the only authentication on the webhook.
  • X-Event is the event name. Branch on this header (or on the
    payload shape).
• At-least-once delivery. Deliveries are queued asynchronously. A
  transient failure on your endpoint will not be retried indefinitely,
  but duplicates are possible. Build idempotent receivers — dedupe
  on id (orders), online_location.id (stores), or your own request
  id if you persist one.
• 2xx = ack. Anything in the 2xx range tells Ewity the webhook was
  delivered. Non-2xx responses are treated as failures.
• Respond fast. Aim to acknowledge inside ~5 seconds — do the heavy
  work asynchronously on your side.
• No HMAC signature is sent today. Authentication is bearer-only. If
  HMAC is a hard requirement for your security model, contact
  [email protected] — we may add per-platform signing as an opt-in.

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.

Events

Order events (delivered to webhook_url)

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

Catalogue events (delivered to inventory_webhook_url)

Recommended catalogue-sync flow

If you've registered an inventory_webhook_url, this is the prescribed flow
to keep your local catalogue cache in sync:

1. Receive a CatalogueUpdated webhook.
2. Group items[].variant_id by online_location_id.
3. For each (online_location_id, variant_ids) group, call
   POST /locations/{online_location_id}/catalogue/lookup
   with {variant_ids}.
4. 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.

This pattern mirrors what your local cache already does for
GET /catalogue — same JSON shape, same out_of_stock semantics. Bulk
operations on the merchant side (CSV imports, stocktakes) coalesce into a
single webhook with a long items array, so you won't be flooded with
hundreds of one-item deliveries.

Each event's link above goes to the API reference page with the exact
request and response shapes, headers, and an example payload.

Receiver checklist

A short list to validate against before going live:

• Verify the Authorization: Bearer ... header matches your
  platform's token. Reject anything else with 401.
• Branch on X-Event (or on the payload shape) to route to the
  right handler.
• Dedupe by event-specific natural keys:
  - OrderStatusChanged / ReviewRequestedReminder: (id, status).
  - StoreTurnedOn: id (debounce to once per N minutes is fine).
  - OrderNotification: (order.id, title, message) is a reasonable proxy.
• 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. For inventory drift, refetch via
  POST /locations/{id}/catalogue/lookup with the IDs you care about.

Configuring your webhook URLs

Webhook URLs are set at the platform level (not per merchant). Register or
change them yourself on your application's Configuration tab in the
Developer Portal — changes take effect
immediately. Both URLs are independent and optional — set only the ones you
need. The bearer token sent with deliveries is your application's API key,
shown on the Credentials tab.