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.

Booking events

Booking events are delivered to every active app granted the location whose allowed scopes include bookings:read and whose subscription matches the event type. They do not require the app to own the POS connection. The location’s bookings rollout flag must be enabled.

Type	Change reported
`booking.created`	Booking created or first observed from its provider
`booking.confirmed`	Request confirmed
`booking.updated`	Booking changed
`booking.cancelled`	Booking cancelled
`booking.declined`	Request declined
`booking.seated`	Party seated
`booking.completed`	Service completed
`booking.no_show`	Party marked no-show

All eight use the same data shape. The embedded booking matches the GET resource:

{
  "location_id": "str_example",
  "previous_status": null,
  "booking": {
    "object": "booking",
    "id": "bkg_example",
    "livemode": false,
    "created": 1789063200,
    "version": 1,
    "location_id": "str_example",
    "status": "confirmed",
    "service_state": null,
    "confirmation_code": "AB1234",
    "starts_at": "2026-09-12T22:00:00.000Z",
    "starts_at_local": "2026-09-12T18:00",
    "service_date": "2026-09-12",
    "duration_minutes": 90,
    "party_size": 2,
    "guest": { "first_name": "Alex", "last_name": "Quinn", "phone": "+12125551234", "phone_last_four": "1234", "email": null },
    "notes": null,
    "channel": "api_partner",
    "provider": "maple",
    "cancellation_policy": null,
    "updated_at": "2026-09-10T18:01:00.000Z"
  }
}

The payload is the latest booking state at first dispatch, not an immutable snapshot of the transition. previous_status is null. An event name can therefore describe an earlier change than the embedded booking’s current status. Once recorded for a recipient, retries keep that payload and event identity. Every original outbox event gets a stable identity per app/environment. Two changes to the same booking remain distinct even when both are dispatched at the same booking version. Dedupe by event ID and reconcile by booking id/version; do not depend on delivery order. The independent developer consumer does not advance the guest-communications cursor. No floor events are forwarded in this release; waitlist changes have their own events. A recipient’s enqueue failure does not stop other eligible apps or subscriptions from being enqueued. Retries reuse the same per-subscription event identity. Booking-event publication uses at most three dispatch attempts, each with bounded internal retries. Malformed internal events and exhausted dispatch attempts are retained for operator investigation instead of blocking later events or retrying forever. This is separate from HTTP webhook delivery retries. Use GET /v1/bookings?updated_since=… to reconcile current booking state after a delivery gap.

Waitlist events

Waitlist events reach the same apps as booking events: every active app granted the location whose allowed scopes include bookings:read and whose subscription matches the event type. They are sent for Maple-native locations while the location’s bookings rollout flag is enabled. See Run the waitlist.

Type	Change reported
`waitlist_entry.created`	A party joined the waitlist
`waitlist_entry.notified`	Maple texted the party that their table is ready
`waitlist_entry.seated`	The party was seated into a walk-in booking
`waitlist_entry.removed`	The party left (`removed_by_guest`) or the venue removed it (`removed_by_venue`)
`waitlist_entry.expired`	A notified party did not respond in time

All five use the same data shape. The embedded waitlist_entry matches GET /v1/waitlist_entries/{entryId}:

{
  "location_id": "str_example",
  "waitlist_entry": {
    "object": "waitlist_entry",
    "id": "bkw_example",
    "livemode": false,
    "created": 1789063200,
    "location_id": "str_example",
    "status": "seated",
    "party_size": 2,
    "position": null,
    "quoted_wait": { "parties_ahead": 1, "wait_minutes": { "min": 15, "max": 30 } },
    "joined_at": "2026-09-10T18:00:00.000Z",
    "notified_at": "2026-09-10T18:20:00.000Z",
    "booking_id": "bkg_example",
    "channel": "api_partner",
    "guest": { "first_name": "Alex", "last_name": "Quinn", "phone": "+12125551234", "phone_last_four": "1234", "email": null }
  }
}

Like booking events, the payload is the latest entry state at first dispatch: a waitlist_entry.created delivered after the party was seated already shows seated. Branch on the event type for what happened, and on waitlist_entry.status for where the entry is now. Each change has its own event ID per app and environment; dedupe by event ID and do not depend on delivery order. Delivery attempts, retries, and quarantine of malformed internal events follow the booking-event rules above. Seating also creates a walk-in booking, which is reported by the booking events you subscribe to.

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

Delivery

Bookings

Core concepts

Tutorials

API reference

Endpoints

Resources

Order events

The `order.notification` payload

Not a status feed

Booking events

Waitlist events

Location (store) events

Menu events

Test event

​Order events

​Which order events should I subscribe to?

​The order.notification payload

​Not a status feed

​Booking events

​Waitlist events

​Location (store) events

​Menu events

​Test event

Order events

Which order events should I subscribe to?

The `order.notification` payload

Not a status feed

Booking events

Waitlist events

Location (store) events

Menu events

Test event