Payloads here are documented from what Maple emits, but they aren’t formally schema-typed yet — new fields may be
added. Validate defensively (ignore unknown fields), and treat GET /v1/orders/{orderId} as the authoritative source
for an order’s current state. The live list of event types is always at GET /v1/webhook_event_types.
data differs by type. This page documents each event type. For signing, delivery, retries, and replay, see Webhooks.
Order events
Order webhooks come in two kinds, and knowing which is which is the key to using them well:
order.notification is the event you fulfill against. It hands you the order’s content to act on, fires once at handoff, and its delivery is treated as critical. Build your accept / deny / ready / complete loop on it.order.created, order.paid, and order.cancelled are lifecycle events. Each reports one moment in the order’s life with summary data, for awareness and reconciliation. Because order.notification fires only once and never updates, these are how you learn about things that happen before or after that snapshot — most importantly a cancellation, or payment settling later.
For the order in which these fire across one order’s life, see When the webhooks fire.
| Type | Fires when | Subscribe to it to… | data |
|---|
order.validation_requested | Before notification — Maple asks you to confirm the order is fulfillable (only if you subscribe) | Pre-validate availability and pricing before the customer is charged | Full order content (same shape as order.notification) |
order.notification | The order is handed to you to fulfill, after validation and payment gating | Receive and fulfill orders — the core of an integration | Full order content (see below) |
order.created | An order is created — earlier than, and thinner than, the notification | Mirror new orders for analytics; catch orders that never reach you (e.g. rejected at validation) | order_id, location_id, status, total, items, created_at |
order.paid | Payment settles — which can be after the handoff (pay-in-store, pay-by-link) | Reconcile payment without polling | order_id, location_id, status, amount, payment_method, payment_source |
order.cancelled | The customer or store cancels — often after you’ve been notified | Stop fulfilling a cancelled order | order_id, location_id, status, reason |
Which order events should I subscribe to?
- Fulfilling orders (a POS):
order.notification and order.cancelled — receive orders, and stop when one is cancelled. Add order.validation_requested if you pre-validate.
- Reporting or reconciliation (an OMS, dashboard, analytics): also
order.created and order.paid, to mirror the order and payment lifecycle.
The order.notification payload
order.notification (and order.validation_requested) carry the order’s content in data — enough to start fulfilling, following the GET /v1/orders/{orderId} shape:
{
"order_id": "ord_...",
"location_id": "str_...",
"fulfillment_type": "pickup",
"customer": { "name": "Alex", "phone_last_four": "1234" },
"line_items": [
{
"name": "Latte",
"menu_entity_id": "itm-latte",
"quantity": 1,
"base_price": 450,
"modifiers": [{ "name": "Oat milk", "menu_entity_id": "mod-oat", "quantity": 1, "price": 75 }]
}
],
"totals": { "currency": "USD", "subtotal": 525, "tax": 42, "surcharge": 0, "tip": 0, "delivery_fee": 0, "delivery_tip": 0, "total": 567 }
}
status or payment. For the authoritative current state (status, payment, per-item tax, timestamps), fetch GET /v1/orders/{orderId}. The lifecycle events carry only the summary fields listed above.
Not a status feed
Maple does not emit a webhook for every status transition. The transitions you drive yourself (accept, ready, complete) aren’t echoed back, and there’s no event for reaching IN_DELIVERY or for payment moving to refunded / voided / failed. Read the order resource for current state — see the Order lifecycle.
Location (store) events
These track your access to a location — the connection lifecycle:
| Type | When it fires | data (indicative) |
|---|
store.provisioned | A merchant granted your app access to a location | location_id |
store.deprovisioned | A grant was revoked; you’ve lost access to the location | location_id |
store.status.changed | Your connection to a location changed | location_id, status (connected / disconnected) |
| Type | When it fires | data (indicative) |
|---|
menu.sync.completed | A menu sync completed for a location | location_id |
menu.sync.failed | A menu sync failed for a location | location_id |
Test event
webhook.test is delivered on demand by POST /v1/webhook_subscriptions/{id}/test. Use it to verify your handler before any real traffic. It is never emitted by real activity.