Webhook events

Transport, signing, retries and idempotency are identical for every event and documented once in Webhooks. This page is the payload catalogue. All events share the envelope:

{
  "event_type": "…",
  "event_id": "9b3e6a1c-4f2d-4e8a-b1c9-7d5e2f8a0c4b",
  "store_id": "st_8fk2c1p9",
  "location_id": "LOC-001",
  "data": { },
  "timestamp": "2026-07-30T12:34:56.000Z"
}

location_id is your external_store_id (also sent as X-Quiqqy-Location-Id), or null when you never set one. Monetary amounts are integers in the currency’s minor unit.

order.created

A new order was placed for an integrated store. data is the full order. Respond by accepting or denying within the SLA — unless auto_accept_orders is on, in which case Quiqqy confirms for you and this event is your ticket to print.

{
  "event_type": "order.created",
  "event_id": "9b3e6a1c-4f2d-4e8a-b1c9-7d5e2f8a0c4b",
  "store_id": "st_8fk2c1p9",
  "location_id": "LOC-001",
  "timestamp": "2026-07-30T12:34:56.000Z",
  "data": {
    "id": "ord_9d31f2",
    "order_number": "ORD-20260730-0042",
    "order_type": "delivery",
    "status": "pending",
    "payment_status": "paid",
    "customer_id": "cus_1a2b3c",
    "currency": "USD",
    "subtotal": 1699,
    "tax": 153,
    "delivery_fee": 200,
    "discount": 0,
    "tip": 0,
    "total_amount": 2052,
    "prices_include_tax": false,
    "special_instructions": null,
    "created_at": "2026-07-30T12:34:56.000Z",
    "items": [
      {
        "product_id": "prd_aa11e8",
        "product_variant_id": "prv_bb22f9",
        "product_name": "Margherita Pizza (Large)",
        "quantity": 1,
        "unit_price": 1699,
        "subtotal": 1699,
        "tax_amount": 153,
        "external_id": "SKU-MARG",
        "variant_external_id": "SKU-MARG-LG",
        "options": []
      }
    ]
  }
}

Key order fields:

Field	Notes
`order_type`	`delivery`, `pickup` or `dine_in`
`status` / `payment_status`	See the lifecycle ladder; `payment_status` is `pending`, `paid`, `failed` or `refunded`
`items[].external_id`, `items[].variant_external_id`	The ids you pushed — app-scoped, `null` for lines your app did not sync (fall back to `product_name`)
`items[].options[]`	Selected add-ons, each with its own app-scoped `external_id`, `name`, `price`
`tax_breakdown`	Per-rate tax detail, present when the store has tax configured

order.updated

The order’s status advanced — Quiqqy-side transitions (courier assigned, out_for_delivery) and echoes of your own status posts. Same data shape as order.created with the current status.

{
  "event_type": "order.updated",
  "event_id": "8b2f4c6d-…",
  "store_id": "st_8fk2c1p9",
  "location_id": "LOC-001",
  "timestamp": "2026-07-30T12:41:00.000Z",
  "data": { "id": "ord_9d31f2", "order_number": "ORD-20260730-0042", "status": "out_for_delivery", "…": "full order as in order.created" }
}

order.cancelled

The order was cancelled — by the customer, by Quiqqy, or as the echo of your own denial. Same data shape, status: "cancelled", plus cancellation_reason when known. Void the ticket and release any held stock.

{
  "event_type": "order.cancelled",
  "event_id": "9c3a5e7f-…",
  "store_id": "st_8fk2c1p9",
  "location_id": "LOC-001",
  "timestamp": "2026-07-30T12:45:00.000Z",
  "data": { "id": "ord_9d31f2", "order_number": "ORD-20260730-0042", "status": "cancelled", "cancellation_reason": "ITEM_OUT_OF_STOCK", "…": "full order as in order.created" }
}

order.delivered

Terminal success — the courier delivered, or the pickup was collected. Same data shape, status: "delivered". Close the ticket.

{
  "event_type": "order.delivered",
  "event_id": "a1d4f8b2-…",
  "store_id": "st_8fk2c1p9",
  "location_id": "LOC-001",
  "timestamp": "2026-07-30T13:10:00.000Z",
  "data": { "id": "ord_9d31f2", "order_number": "ORD-20260730-0042", "status": "delivered", "…": "full order as in order.created" }
}

menu.updated

The store’s synced menu changed on the Quiqqy side — a merchant edit in the dashboard, or a completed sync job. Relevant mainly for quiqqy_to_pos and bidirectional integrations that mirror Quiqqy edits back into the POS.

{
  "event_type": "menu.updated",
  "event_id": "d4b7a2c9-…",
  "store_id": "st_8fk2c1p9",
  "location_id": "LOC-001",
  "timestamp": "2026-07-30T08:02:11.000Z",
  "data": {
    "menu_external_id": "menu-main",
    "changed": ["items", "categories"],
    "source": "merchant_portal"
  }
}

The payload is a change notice, not a diff — fetch or re-sync what you need.

menu.item_availability_changed

An item was 86’d or restored on the Quiqqy side — a merchant toggle, or a snooze_until expiring. Mirror it in the POS so both sides agree on what is sellable.

{
  "event_type": "menu.item_availability_changed",
  "event_id": "e5c8b3d0-…",
  "store_id": "st_8fk2c1p9",
  "location_id": "LOC-001",
  "timestamp": "2026-07-30T18:20:05.000Z",
  "data": {
    "items": [
      { "external_id": "SKU-BURRATA", "available": false, "snooze_until": "2026-07-31T04:00:00.000Z" },
      { "external_id": "SKU-TIRAMISU", "available": true, "snooze_until": null }
    ],
    "changed_by": "merchant_dashboard"
  }
}

store.status_changed

The store went live or was paused — from the merchant dashboard, your own status call, or Quiqqy operations.

{
  "event_type": "store.status_changed",
  "event_id": "f6d9c4e1-…",
  "store_id": "st_8fk2c1p9",
  "location_id": "LOC-001",
  "timestamp": "2026-07-30T15:00:00.000Z",
  "data": {
    "status": "inactive",
    "previous_status": "active",
    "changed_by": "merchant_portal"
  }
}

status is active (accepting online orders) or inactive (paused); changed_by names where the change came from.

action_required

Quiqqy asks your integration to do something. The command is data.action, mirrored into the X-Quiqqy-Action header so you can dispatch without parsing (data.request_type is a legacy alias of data.action). Acknowledge with 2xx, then perform the action.

`data.action`	What to do
`menu_push`	Push the latest full menu — Menu sync
`resync`	Re-sync the whole catalogue; treat exactly as `menu_push`

{
  "event_type": "action_required",
  "event_id": "b2e5d7a3-…",
  "store_id": "st_8fk2c1p9",
  "location_id": "LOC-001",
  "timestamp": "2026-07-30T09:00:00.000Z",
  "data": {
    "action": "menu_push",
    "request_type": "menu_push",
    "app_id": "app_7pk2mv9qx4rt",
    "integration_id": "int_3a2c8d1e",
    "requested_by": "developer_portal"
  }
}

Test deliveries

The console’s test button (and POST /pos/stores/:storeId/webhooks/:id/test) sends the normal envelope with minimal data: store_id is null, location_id is "test-location", and data contains { "test": true }. Use it to verify reachability and signature handling — never create a real order from it.