> ## Documentation Index
> Fetch the complete documentation index at: https://docs.maple.inc/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook events

> The catalog of webhook event types and the payload each one carries.

<Note>
  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`.
</Note>

Every webhook is delivered in the same [signed envelope](/developer-api/concepts/webhooks#the-event-envelope); only the `data` differs by `type`. This page documents each event type. For signing, delivery, retries, and replay, see [Webhooks](/developer-api/concepts/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](/developer-api/concepts/order-lifecycle#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:

```json theme={null}
{
  "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 }
}
```

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}`](/developer-api/concepts/order-lifecycle). 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](/developer-api/concepts/order-lifecycle#webhooks-dont-track-every-transition).

## Location (store) events

These track your access to a location — the [connection lifecycle](/developer-api/concepts/entities#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`) |

## Menu events

| 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](/developer-api/guides/publish-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.