Order webhooks

{
  "id": "wh_0193f0c2-7a1b-7c3d-9e4f-0123456789ab",
  "type": "order.status.changed",
  "created_at": "2026-06-17T14:32:00.000Z",
  "data": {
    "merchant_id": "8f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
    "order_id": "ord-48291",
    "fulfillment_id": "delivery",
    "store_id": "downtown",
    "channel_id": "app",
    "brand_id": "0001",
    "customer_id": "cust-001",
    "status": "injecting",
    "current_states": ["injecting"],
    "next_states": ["injected"],
    "order": {
      "uid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "id": "ord-48291",
      "brand_id": "0001",
      "store_id": "downtown",
      "channel_id": "app",
      "customer_id": "cust-001",
      "is_anonymous": false,
      "fulfillment_id": "delivery",
      "status": "CLOSED",
      "payment_status": "PAID",
      "fulfillment_status": "INJECTING",
      "lines": [
        {
          "type": "PRODUCT",
          "uid": "f6a7b8c9-d0e1-2345-f678-901234567890",
          "id": "burger-classic",
          "parent_uid": null,
          "parent_id": null,
          "name": "Classic burger",
          "metadata": {},
          "quantity": 1,
          "tax_rate": 0.15,
          "discount_rate": 0,
          "unit_subtotal": 12.99,
          "unit_discount": 0,
          "unit_tax_total": 1.95,
          "unit_total": 14.94,
          "subtotal": 12.99,
          "discount_total": 0,
          "tax_total": 1.95,
          "total": 14.94,
          "unit_group_subtotal": 12.99,
          "unit_group_discount": 0,
          "unit_group_tax_total": 1.95,
          "unit_group_total": 14.94,
          "group_subtotal": 12.99,
          "group_discount": 0,
          "group_tax_total": 1.95,
          "group_total": 14.94
        }
      ],
      "customer": {
        "customer_info": {
          "display_name": "Jane Doe",
          "first_name": "Jane",
          "last_name": "Doe",
          "email": "jane@example.com",
          "phone": "+593991234567"
        },
        "address_info": {
          "name": "Jane Doe",
          "email": "jane@example.com",
          "phone": "+593991234567",
          "address_line1": "Av. Amazonas 123",
          "unit_number": "4B",
          "postal_code": "170150",
          "city": "Quito",
          "country": "Ecuador"
        }
      },
      "payment_intents": [
        {
          "id": "pi_card",
          "status": "LOCKED",
          "is_mixed": false,
          "primary_tender_id": "tnd_card",
          "rules_snapshot": null,
          "metadata": {},
          "totals": {
            "currency": "USD",
            "subtotal": 12.99,
            "discount_rate": 0,
            "discount_total": 0,
            "tax_rate": 0.15,
            "tax_total": 1.95,
            "total": 14.94
          },
          "placed_at": "2026-06-17T14:31:45.000Z",
          "tenders": [
            {
              "id": "tnd_card",
              "sequence": 0,
              "attempt_reference": "att_card_1",
              "method": "CARD",
              "provider": "kushki",
              "collect_at": "DEVICE",
              "status": "PAID",
              "refunded_total": 0,
              "allocation": null,
              "amount": {
                "currency": "USD",
                "total": 14.94
              },
              "details": null,
              "metadata": {},
              "placed_at": "2026-06-17T14:31:45.000Z",
              "resolved_at": "2026-06-17T14:31:50.000Z"
            }
          ]
        }
      ],
      "totals": {
        "currency": "USD",
        "subtotal": 12.99,
        "discount_rate": 0,
        "discount_total": 0,
        "tax_rate": 0.15,
        "tax_total": 1.95,
        "total": 14.94
      },
      "metadata": {},
      "issued_at": "2026-06-17T14:31:45.000Z"
    }
  }
}

{
  "id": "wh_0193f0c2-7a1b-7c3d-9e4f-0123456789ab",
  "type": "order.status.changed",
  "created_at": "2026-06-17T14:32:00.000Z",
  "data": {
    "merchant_id": "8f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
    "order_id": "ord-48291",
    "fulfillment_id": "delivery",
    "store_id": "downtown",
    "channel_id": "app",
    "brand_id": "0001",
    "customer_id": "cust-001",
    "status": "injecting",
    "current_states": ["injecting"],
    "next_states": ["injected"],
    "order": {
      "uid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "id": "ord-48291",
      "brand_id": "0001",
      "store_id": "downtown",
      "channel_id": "app",
      "customer_id": "cust-001",
      "is_anonymous": false,
      "fulfillment_id": "delivery",
      "status": "CLOSED",
      "payment_status": "PAID",
      "fulfillment_status": "INJECTING",
      "lines": [
        {
          "type": "PRODUCT",
          "uid": "f6a7b8c9-d0e1-2345-f678-901234567890",
          "id": "burger-classic",
          "parent_uid": null,
          "parent_id": null,
          "name": "Classic burger",
          "metadata": {},
          "quantity": 1,
          "tax_rate": 0.15,
          "discount_rate": 0,
          "unit_subtotal": 12.99,
          "unit_discount": 0,
          "unit_tax_total": 1.95,
          "unit_total": 14.94,
          "subtotal": 12.99,
          "discount_total": 0,
          "tax_total": 1.95,
          "total": 14.94,
          "unit_group_subtotal": 12.99,
          "unit_group_discount": 0,
          "unit_group_tax_total": 1.95,
          "unit_group_total": 14.94,
          "group_subtotal": 12.99,
          "group_discount": 0,
          "group_tax_total": 1.95,
          "group_total": 14.94
        }
      ],
      "customer": {
        "customer_info": {
          "display_name": "Jane Doe",
          "first_name": "Jane",
          "last_name": "Doe",
          "email": "jane@example.com",
          "phone": "+593991234567"
        },
        "address_info": {
          "name": "Jane Doe",
          "email": "jane@example.com",
          "phone": "+593991234567",
          "address_line1": "Av. Amazonas 123",
          "unit_number": "4B",
          "postal_code": "170150",
          "city": "Quito",
          "country": "Ecuador"
        }
      },
      "payment_intents": [
        {
          "id": "pi_card",
          "status": "LOCKED",
          "is_mixed": false,
          "primary_tender_id": "tnd_card",
          "rules_snapshot": null,
          "metadata": {},
          "totals": {
            "currency": "USD",
            "subtotal": 12.99,
            "discount_rate": 0,
            "discount_total": 0,
            "tax_rate": 0.15,
            "tax_total": 1.95,
            "total": 14.94
          },
          "placed_at": "2026-06-17T14:31:45.000Z",
          "tenders": [
            {
              "id": "tnd_card",
              "sequence": 0,
              "attempt_reference": "att_card_1",
              "method": "CARD",
              "provider": "kushki",
              "collect_at": "DEVICE",
              "status": "PAID",
              "refunded_total": 0,
              "allocation": null,
              "amount": {
                "currency": "USD",
                "total": 14.94
              },
              "details": null,
              "metadata": {},
              "placed_at": "2026-06-17T14:31:45.000Z",
              "resolved_at": "2026-06-17T14:31:50.000Z"
            }
          ]
        }
      ],
      "totals": {
        "currency": "USD",
        "subtotal": 12.99,
        "discount_rate": 0,
        "discount_total": 0,
        "tax_rate": 0.15,
        "tax_total": 1.95,
        "total": 14.94
      },
      "metadata": {},
      "issued_at": "2026-06-17T14:31:45.000Z"
    }
  }
}

When a customer places an order on any connected channel, Fire spark POSTs the order to the HTTPS URLs you register in the dashboard. Your integration does not poll for new tickets.

How orders reach your kitchen

Customer places the order

Storefront or a channel closes the cart. Fire spark starts fulfillment and notifies any matching webhooks.

The order reaches a subscribed status

Subscribe to order.status.changed and pick the statuses you care about (injecting, preparing, and so on). Named events cover void, fulfill, refund, and reverse.

Create the kitchen ticket

For handoff to POS or RMS, include injecting in those statuses. The payload has the full order — create the ticket as sent.

Report the next status from your POS

Call Update order status with the next fulfillment status. Fire spark may send another webhook.

Kitchen handoff is order.status.changed with data.status injecting. There is no separate injection event. Create the ticket from the payload as sent.

Configure your endpoint

Register HTTPS URLs under Settings → Webhooks in the Fire spark dashboard (up to 10 per environment). Each environment has its own endpoints, and an order only notifies the endpoints of its environment. Choose Webhook or Callback.

Webhook — fire-and-forget after that node’s work is closed (persisted, settled, callbacks finished). A waiting node is WAITING before the POST. An automatic next node is notified before it is entered. A terminal is notified after the run is finalized. A failed callback does not send that node’s webhook. Pick one or more events. For order.status.changed you must also pick the statuses that should fire (injecting, paid, preparing, …).
Callback — Fire spark waits for your 2xx when a node that lists this endpoint is entered. Events do not apply. You can register the same URL once as each type.

Requirement	Detail
Protocol	HTTPS only
Timeout	Per request, 1–300 seconds (default 5)
Retries	After the first failure, 0–10 (default 3). Delay is `min(1000 × 2^n, 30000)` ms — same as TanStack Query
Response	Return `2xx` within `timeout`. For `INJECTING` callbacks, the JSON body must include `order_authorization_id` and `injection_order_id`
Delivery	One POST per matching event and trigger status (webhooks). One awaited POST per attempt (callbacks)
Idempotency	Use envelope `id` (`wh_…` or `cb_…`) to ignore duplicates
Signature	Optional. If you generate a secret, deliveries include `X-Firespark-Signature`

Webhooks created before signing support only stored a one-way hash. Rotate (regenerate) the secret in the dashboard if you need HMAC verification.

Signature

When a secret is present, Fire spark sets:

X-Firespark-Event: order.status.changed
X-Firespark-Delivery: wh_…
X-Firespark-Signature: sha256=<hex>

<hex> is HMAC-SHA256 of the raw JSON body using the secret shown once at create/rotate time (whsec_…).

Event types

There is no order.created or order.updated event. Subscribe to the events that match how you run the kitchen:

Event	Fires when	Typical use
`order.status.changed`	The order reaches a status you selected	Create the POS ticket on `injecting`; sync later steps
`order.voided`	The order status is `VOIDED` (unpaid cancel, or reopen)	Void the matching ticket. `data.status` is `voided`.
`order.fulfilled`	The order is fulfilled	Close the ticket as fulfilled
`order.refunded`	The order is refunded	Process the refund in your POS
`order.reversed`	A paid order was reversed after a failed callback	Void the ticket and reverse capture
`order.cancelled`	Subscribable in the dashboard	The status mapper does not emit this event. New cancels write `VOIDED` and fire `order.voided`.

A webhook subscribed to both order.status.changed (status voided) and order.voided receives two POSTs. Use type plus id to tell them apart. data.status is the status that triggered that POST.

Values you will receive

These are the closed sets. Everything else on data.order follows Get order.

`type` and headers

Field / header	Allowed values
`type` and `X-Firespark-Event`	`order.status.changed` \| `order.voided` \| `order.fulfilled` \| `order.refunded` \| `order.reversed` \| `order.cancelled` \| `order.callback`
`Content-Type`	`application/json`
`X-Firespark-Delivery`	Same as envelope `id` (`wh_…`)
`X-Firespark-Signature`	`sha256=<hex>` when the webhook has a secret; omitted otherwise

`data.status`, `current_states`, `next_states`

Always lowercase snake_case. Hyphens become underscores (awaiting-pickup-time → awaiting_pickup_time). data.status is always in current_states. next_states lists the upcoming happy-path statuses you can advance this order to from here — not the statuses just entered. Terminals (fulfilled, voided, refunded, reversed) are omitted; they still fire named events when entered. Use a value from next_states when you PATCH order status. These are not a fixed enum — they are the fulfillment statuses configured for the merchant. Default Fire spark paths use:

Key	Typical meaning
`injecting`	Ready for the POS / kitchen
`injected`	POS / RMS accepted the order
`idle`	Not started
`paying`	Waiting for payment
`paid`	Payment captured
`preparing`	Kitchen started
`prepared`	Ready for pickup or courier
`awaiting_pickup_time`	Scheduled pickup not yet due
`courier_heading_to_store`	Courier en route to the store
`courier_at_store`	Courier at the store
`delivering`	Out for delivery
`delivered`	Handed to the customer
`fulfilled`	Fulfillment complete
`voided`	Order status `VOIDED`: unpaid cancel, or the source order of a reopen
`cancelled`	Legacy fulfillment key. New cancels use `voided`.
`refunded`	Refunded (explicit refund path)
`reversed`	Paid order reversed after a failed callback

The merchant can add other keys (same snake_case pattern: a-z, 0-9, underscores). Subscribe to the keys shown in Settings → Webhooks. Named events fire only for these keys:

`type`	`data.status`
`order.voided`	`voided`
`order.fulfilled`	`fulfilled`
`order.refunded`	`refunded`
`order.reversed`	`reversed`

delivered does not fire order.fulfilled. Subscribe to order.status.changed and include delivered if you need that step.

`data.order` status fields

Field	Allowed values
`status`	`OPEN` \| `CLOSED` \| `COMPLETED` \| `VOIDED` \| `REVERSED` \| `REFUNDED` \| `CANCELLED` (legacy rows)
`payment_status`	`IDLE` \| `PENDING` \| `PAID` \| `FAILED` \| `CANCELLED` \| `REFUNDED`
`fulfillment_status`	Merchant label as configured, usually `UPPER_SNAKE` (`INJECTING`). Not the same casing as `data.status`.
`payment_intents[].status`	`DRAFT` \| `LOCKED` \| `COMPLETED` \| `ABANDONED`
`payment_intents[].tenders[].method`	`CASH` \| `CARD` \| `BANK_TRANSFER` \| `WALLET` \| `PIN_PAD` \| `FINANCING` \| `REDEMPTION`
`payment_intents[].tenders[].collect_at`	`DEVICE` \| `KIOSK` \| `COUNTER` \| `DOOR` \| `OTHER`
`payment_intents[].tenders[].status`	Same as `payment_status`
`lines[].type`	`PRODUCT` \| `FEE`

Delivery

Webhooks: one attempt per POST, 10 second timeout. Any 2xx counts as success. Fire spark does not retry automatically. Callbacks: first POST is immediate. After each failure, wait min(1000 × 2^failureCount, 30000) ms and retry while failureCount < retries (default 3 → 4 POSTs max). Each POST uses the endpoint timeout (default 5s, max 300s). Invalid JSON for a registered schema (today INJECTING) counts as a failure. If retries are exhausted, Fire spark enters VOIDED (unpaid) or REVERSED (paid) and does not wait for PATCH.

Webhook payload

Every delivery is the same envelope:

Field	Required	Type	Description
`id`	Yes	string	Unique delivery id. Use for idempotency
`type`	Yes	string	`order.status.changed`, `order.voided`, `order.fulfilled`, `order.refunded`, `order.reversed`, `order.cancelled`, or `order.callback`
`created_at`	Yes	string	ISO 8601 timestamp when the delivery was built
`data`	Yes	object	Order, scope ids, trigger status, and current statuses

`data` object

Field	Required	Type	Description
`merchant_id`	Yes	string	Merchant that owns the order
`order_id`	Yes	string	External order id (same as `/orders/{id}`)
`fulfillment_id`	Yes	string	External fulfillment option (`delivery`, `pickup`, …)
`store_id`	Yes	string	External store
`channel_id`	Yes	string	External channel
`brand_id`	Yes	string \| null	External brand when the order has one
`customer_id`	Yes	string	External customer
`status`	Yes	string	Fulfillment status that triggered this POST
`current_states`	Yes	string[]	Every fulfillment status the order is in now. Always includes `status`. Parallel work can add more
`next_states`	Yes	string[]	Upcoming happy-path statuses you can PATCH to from `current_states`. Empty when only terminals remain
`order`	Yes	object	Full order after this transition (integrations shape)

data.status is this delivery’s trigger. current_states is the full picture right now — the trigger plus any other statuses still in progress (for example kitchen and delivery at the same time). next_states is what you can PATCH next from those current statuses. If two subscribed statuses are entered together, you get one POST per status, each with the same current_states and next_states. order.fulfillment_status is the latest fulfillment status on the order. order.status is the overall lifecycle (OPEN, CLOSED, …), not the webhook trigger.

{
  "id": "wh_0193f0c2-7a1b-7c3d-9e4f-0123456789ab",
  "type": "order.status.changed",
  "created_at": "2026-06-17T14:32:00.000Z",
  "data": {
    "merchant_id": "8f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
    "order_id": "ord-48291",
    "fulfillment_id": "delivery",
    "store_id": "downtown",
    "channel_id": "app",
    "brand_id": "0001",
    "customer_id": "cust-001",
    "status": "injecting",
    "current_states": ["injecting"],
    "next_states": ["injected"],
    "order": {
      "uid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "id": "ord-48291",
      "brand_id": "0001",
      "store_id": "downtown",
      "channel_id": "app",
      "customer_id": "cust-001",
      "is_anonymous": false,
      "fulfillment_id": "delivery",
      "status": "CLOSED",
      "payment_status": "PAID",
      "fulfillment_status": "INJECTING",
      "lines": [
        {
          "type": "PRODUCT",
          "uid": "f6a7b8c9-d0e1-2345-f678-901234567890",
          "id": "burger-classic",
          "parent_uid": null,
          "parent_id": null,
          "name": "Classic burger",
          "metadata": {},
          "quantity": 1,
          "tax_rate": 0.15,
          "discount_rate": 0,
          "unit_subtotal": 12.99,
          "unit_discount": 0,
          "unit_tax_total": 1.95,
          "unit_total": 14.94,
          "subtotal": 12.99,
          "discount_total": 0,
          "tax_total": 1.95,
          "total": 14.94,
          "unit_group_subtotal": 12.99,
          "unit_group_discount": 0,
          "unit_group_tax_total": 1.95,
          "unit_group_total": 14.94,
          "group_subtotal": 12.99,
          "group_discount": 0,
          "group_tax_total": 1.95,
          "group_total": 14.94
        }
      ],
      "customer": {
        "customer_info": {
          "display_name": "Jane Doe",
          "first_name": "Jane",
          "last_name": "Doe",
          "email": "jane@example.com",
          "phone": "+593991234567"
        },
        "address_info": {
          "name": "Jane Doe",
          "email": "jane@example.com",
          "phone": "+593991234567",
          "address_line1": "Av. Amazonas 123",
          "unit_number": "4B",
          "postal_code": "170150",
          "city": "Quito",
          "country": "Ecuador"
        }
      },
      "payment_intents": [
        {
          "id": "pi_card",
          "status": "LOCKED",
          "is_mixed": false,
          "primary_tender_id": "tnd_card",
          "rules_snapshot": null,
          "metadata": {},
          "totals": {
            "currency": "USD",
            "subtotal": 12.99,
            "discount_rate": 0,
            "discount_total": 0,
            "tax_rate": 0.15,
            "tax_total": 1.95,
            "total": 14.94
          },
          "placed_at": "2026-06-17T14:31:45.000Z",
          "tenders": [
            {
              "id": "tnd_card",
              "sequence": 0,
              "attempt_reference": "att_card_1",
              "method": "CARD",
              "provider": "kushki",
              "collect_at": "DEVICE",
              "status": "PAID",
              "refunded_total": 0,
              "allocation": null,
              "amount": {
                "currency": "USD",
                "total": 14.94
              },
              "details": null,
              "metadata": {},
              "placed_at": "2026-06-17T14:31:45.000Z",
              "resolved_at": "2026-06-17T14:31:50.000Z"
            }
          ]
        }
      ],
      "totals": {
        "currency": "USD",
        "subtotal": 12.99,
        "discount_rate": 0,
        "discount_total": 0,
        "tax_rate": 0.15,
        "tax_total": 1.95,
        "total": 14.94
      },
      "metadata": {},
      "issued_at": "2026-06-17T14:31:45.000Z"
    }
  }
}

Callback response (`INJECTING`)

When a fulfillment node mapped to INJECTING invokes a callback, a 2xx is not enough. Return JSON:

{
  "order_authorization_id": "auth-48291",
  "injection_order_id": "pos-9912"
}

Both fields use the same id rules as other external ids (1–64 characters, a-zA-Z0-9_-). Fire spark stores them on order.metadata so they appear on Get order and later webhook payloads. A 2xx with a body that fails this schema counts as a failed attempt. When a kiosk channel uses pagers, the customer types the number of the pager they took before paying. Fire spark saves it on order.metadata.pager, so it comes with the INJECTING callback and later webhooks:

{
  "metadata": {
    "pager": { "number": "07", "side": "RIGHT" }
  }
}

Field	Type	Notes
`number`	string	Zero-padded to the digits of the last pager in the range (`7` of `01–99` is `"07"`). Always within the configured range.
`side`	`"LEFT"` \| `"RIGHT"`	Side of the kiosk where the pager stand is.

metadata.pager is null or missing when pagers are off, when the chosen payment method doesn’t use them, or when the customer skipped an optional pager. Print the number on the ticket so staff can find the customer.

Handling kitchen handoff

Subscribe to order.status.changed and include injecting.
Read data.status, data.order_id, scope ids, and the full data.order.
Map fulfillment_id, store_id, channel_id, brand_id, and line id values to your POS catalog (same external ids as menu sync).
Create the ticket using totals, customer, payment, and fulfillment fields as sent. Include order.metadata.pager.number when present.
Return HTTP 2xx quickly.
When the kitchen moves on, PATCH order status with the next fulfillment status.

Guard against duplicate tickets: the same order_id can be delivered more than once. Key on envelope id, or on order_id plus data.status.

Fetching an order manually

Call Get order with the external order_id when you need to reconcile. Requires the orders:read scope. Every webhook already includes the full order object, so this is optional.

Get order

Retrieve the full order by external id

Update order status

Report the next fulfillment status from your POS

API Documentation

Endpoints

Guides

Resources

How orders reach your kitchen

Configure your endpoint

Signature

Event types

Values you will receive

`type` and headers

`data.status`, `current_states`, `next_states`

`data.order` status fields

Delivery

Webhook payload

`data` object

Callback response (`INJECTING`)

Handling kitchen handoff

Fetching an order manually

Get order

Update order status

​How orders reach your kitchen

​Configure your endpoint

​Signature

​Event types

​Values you will receive

​type and headers

​data.status, current_states, next_states

​data.order status fields

​Delivery

​Webhook payload

​data object

​Callback response (INJECTING)

​Kiosk pagers (metadata.pager)

​Handling kitchen handoff

​Fetching an order manually

​Related endpoints

Get order

Update order status

How orders reach your kitchen

Configure your endpoint

Signature

Event types

Values you will receive

`type` and headers

`data.status`, `current_states`, `next_states`

`data.order` status fields

Delivery

Webhook payload

`data` object

Callback response (`INJECTING`)

Kiosk pagers (`metadata.pager`)

Handling kitchen handoff

Fetching an order manually

Related endpoints