Webhook events

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.

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) plus validation_id
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. It uses the same field names and integer-cent amounts as the order resource, but is a smaller object with these keys (as with every payload, ignore keys you don’t recognize):

{
  "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 }
}

order.validation_requested carries the same data plus a validation_id. Echo it in your POST /v1/orders/{orderId}/validation_result so the result is bound to this attempt; a result for an expired or older attempt is rejected. See Receive orders.

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,
    "experience": 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)

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.

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.