Webhook events

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.

Every webhook is delivered in the same signed envelope; only the 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`

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": "delivery",
  "scheduled_for": null,
  "delivery_address": {
    "street": "123 Main Street",
    "unit": "Apt 4B",
    "city": "New York",
    "state": "NY",
    "zip": "10001",
    "notes": "Leave at the side door"
  },
  "customer": { "name": "Alex", "phone": "+14155551234", "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": 599, "delivery_tip": 0, "total": 1166 }
}

This is the order’s content, not its live state — it has no 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. scheduled_for is null for ASAP orders. When set (ISO 8601, UTC), the customer chose that pickup/delivery time — the notification still arrives immediately, so prepare the order for scheduled_for, not on receipt. delivery_address is null for pickup orders and for delivery orders without a stored address. When present, all six keys are included; notes contains the delivery instructions and unit or notes may be null.

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`

See Publish a menu.

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.

Get started

Orders

Menus

Core concepts

Tutorials

API reference

Endpoints

Resources

Order events

The `order.notification` payload

Not a status feed

Location (store) events

Menu events

Test event

​Order events

​Which order events should I subscribe to?

​The order.notification payload

​Not a status feed

​Location (store) events

​Menu events

​Test event

Order events

Which order events should I subscribe to?

The `order.notification` payload

Not a status feed

Location (store) events

Menu events

Test event