Webhook event reference
What this covers
All fifty-four events, when each fires, and what to key on. Requires the Webhooks feature.
Reservations
| Event | Fires when |
|---|---|
reservation.created | Any booking is created — staff, online, chatbot, walk-in or API |
reservation.updated | Date, time, pax, table, duration, requests, notes or the guest change |
reservation.confirmed | Status becomes confirmed |
reservation.arrived | The guest is marked arrived |
reservation.seated | The guest is seated |
reservation.completed | The visit is completed |
reservation.cancelled | Cancelled, by staff or guest |
reservation.no_show | Marked a no-show, by hand or by the automatic sweep |
reservation.reminder_sent | A reminder went to the guest. notification says the channel (email or sms) |
reservation.notification_failed | A message to the guest couldn't be delivered after every attempt. notification has the channel, the type (confirmation, reminder, update, cancellation) and the error class — never the error text |
reservation.deleted | A reservation is permanently deleted from the app (rather than cancelled). The payload is the record as it was just before deletion |
The status events are what make a live kitchen or floor display possible. Note arrived,
seated and completed fire webhooks even though they send the guest nothing (link
What Tabledoo sends, and when).
What reservation.updated carries
Alongside the current record, reservation.updated includes a changes object listing each field that changed with its old and new value — for example {"party_size": {"old": 2, "new": 4}}. A table change appears as table_id with the table name(s), such as {"old": "T4", "new": "T4 + T5"}. Edits saved together arrive as one event, so changing the time and the table in one go produces a single reservation.updated with both entries.
Housekeeping the guest never asked for — a reminder being sent, for instance — does not fire an update.
Walk-ins and event bookings
Walk-ins fire the full set. A walk-in is an ordinary booking with a walk-in source, so it
produces reservation.created and every status event that follows.
Event bookings are a separate kind of record and fire their own event_booking.*
events, listed below — not reservation events (link
Taking event bookings).
Guests
| Event | Fires when |
|---|---|
guest.created | A guest profile is created — including automatically, from an online or chatbot booking |
guest.updated | Guest details change |
guest.deleted | A guest profile is deleted. The payload is the profile as it was just before deletion |
These are what a CRM sync should listen to. Deleting a guest removes them from the list only — their bookings stay, so no booking events follow. When guest data is erased, you receive a single guest.deleted whose payload is already anonymised. Remember profiles are created automatically when an unknown
guest books, so guest.created fires more often than staff adding people by hand.
Waitlist
| Event | Fires when |
|---|---|
waitlist.created | A party is added to the waitlist |
waitlist.updated | An entry's party size, date, time, duration, notes or guest change |
waitlist.notified | The party is told their table is ready |
waitlist.converted | A waitlist entry becomes a real booking (a reservation.created follows for the new booking) |
waitlist.cancelled | An entry is cancelled |
waitlist.no_show | An entry is closed as a no-show — the party did not show up |
waitlist.deleted | An entry is permanently deleted. The payload is the record as it was just before deletion |
Pair these with the waitlist API: read the queue with GET /waitlist, and let these events tell you when it changes instead of polling. A wait-time display or a queue screen is built that way. The payload carries guest_id and, once converted, the reservation_id of the booking it became (link API reference, The waitlist).
Orders
| Event | Fires when |
|---|---|
order.placed | Guests submit an order from a table |
order.status_updated | An order moves — confirmed, preparing, served |
order.item.status_updated | A single item moves |
order.cancelled | An order is cancelled |
order.updated | A guest changes what is on an order that is still open. items is the complete new list of lines, not a difference — replace what you had |
What an order payload contains
order.placed, order.status_updated and order.cancelled carry the whole
order in data, including its line items in items — so your till
does not have to call back to find out what was ordered. order.placed is sent once the order and all of
its lines are saved. Each line has the ids menu_item_id, menu_external_id,
category_external_id and item_external_id, the menu_item_name as it was
ordered, quantity, unit_price, notes, status, and its
selected_options (each with option_external_id and option_group_external_id).
order.item.status_updated carries the same identifiers for the one line that moved.
"items": [{
"id": 311, "menu_item_id": 42, "menu_item_name": "Classic Burger",
"menu_external_id": "POS-MENU-1", "category_external_id": "POS-CAT-9", "item_external_id": "POS-ITEM-42",
"quantity": 2, "unit_price": 12.0, "notes": "no onions", "status": "pending",
"selected_options": [{ "name": "Large", "option_external_id": "POS-OPT-L", "option_group_external_id": "POS-GRP-1" }]
}]
Because order and item status stay in step both ways, a single action can produce both an order event and item events. Decide which level your integration keys on and ignore the other, or you will double-count (link The Orders board).
Summons
| Event | Fires when |
|---|---|
summon.created | A guest calls a waiter or requests the bill (check event_type: waiter_summoned or bill_requested) |
summon.cleared | Staff clear it, in the app or through the API |
The one genuinely time-critical pair — a guest waiting with a raised hand. If you are driving a floor buzzer or a staff watch, these are the events, and your endpoint's response time matters (link Call waiter and request bill).
Events
| Event | Fires when |
|---|---|
event.created | An event is created (always as a draft) |
event.updated | Its details change — title, description, type, pax range, capacity, price, tables, schedule, cut-off or image. changes lists old and new values |
event.published | A draft goes live |
event.cancelled | The whole event is cancelled (each booking also sends its own event_booking.cancelled) |
event.deleted | An event is deleted. The payload is the event as it was just before |
event_slot.cancelled | One date is cancelled, on its own or because the whole event was |
The payload is the event as GET /events/{id} returns it; event_slot.cancelled carries the date (slot_date, starts_at, status) and the event's id, title and slug. Use them to keep a website or listings feed in step with what is on. Only an event with no bookings can be deleted, so deleting never silently removes bookings.
Chat
| Event | Fires when |
|---|---|
chat.session_started | A visitor opens a conversation with the booking chatbot |
The payload is only the session id and started_at: the visitor's token, IP address and browser are never sent.
Table sessions
| Event | Fires when |
|---|---|
table_session.opened | A guest scans a table's QR code and a new ordering session starts |
table_session.closed | The session ends. reason is staff_closed, idle_timeout (nobody touched it for the idle period) or replaced (someone started a new session at the same table) |
Use these to know when a table is being used for QR ordering. The payload has the session id, the table, covers and the opened, last-activity and closed times. The session's own secret token is never included.
Phone
| Event | Fires when |
|---|---|
call.incoming | The phone system reports a call — at the same moment the caller pops up on staff screens |
The payload has the caller's number (phone), whether it is withheld, the number dialed, and match: type is guest (one guest found, in match.guest), candidates (several possible guests, listed in match.candidates), none or withheld. It is time-critical, so it is retried within seconds and then given up on. A repeat of the same call within 90 seconds is not sent again, and a call your phone settings suppress (withheld numbers or numbers with no match, when those pops are switched off) sends nothing.
Menu
| Event | Fires when |
|---|---|
menu.created, menu.updated, menu.deleted | A menu is created, its name, description, currency, languages, active/public setting or external id changes, or it is deleted |
menu_category.created, .updated, .deleted | A category is created, renamed, switched on or off, moved to another menu, given a new external id, or deleted |
menu_item.created, .updated, .deleted | An item is created, or its name, description, price, availability, allergens, tags, image, category or external id changes, or anything about its options changes, or it is deleted |
These are what let a POS mirror the menu, including changes staff make in the app — an
item marked Sold out, a price edit, a new dish. Item payloads carry the whole item: its option groups and
options, and the ids of its category and menu (category_external_id,
menu_external_id) alongside your own external_id. Category and menu payloads are just
the category or menu itself, without their contents.
Options report on their item
Option groups and options do not have events of their own. Adding, removing or changing one arrives as a
menu_item.updated for the item it belongs to, and the changes object says what moved
— for example {"option:87.price_modifier": {"old": "2.00", "new": "2.50"}}. An update carries
changes as old and new values for each field that changed; sort order and translations do not
count as changes.
Deleting a category or a whole menu
Removing a category also removes its items, and removing a menu removes its categories and items. You receive
a menu_item.deleted for each item and a menu_category.deleted for each category, as
well as the one for the category or menu itself, each carrying what it looked like just before deletion. A
category or item created and removed in the same save is never announced.
Ignoring your own changes: source
Every menu event has a source: api when the change came in through the API (for
example your own PUT /menus sync) and app when someone changed it in Tabledoo. If your
integration writes to the menu, ignore events with source: api or it will be told about its own
changes.
A large sync sends one event per changed row — a sync that changes 300 items sends 300
menu_item.updated events, and rows that did not change send nothing. They count against your monthly
delivery allowance, so subscribe to the menu events only if you act on them (link
API reference).
The payload
Every delivery uses the same envelope, whatever the event:
{
"event": "reservation.confirmed",
"timestamp": "2026-10-02T18:14:22+00:00",
"api_version": "v1",
"tenant": { "property_code": "oldbell", "name": "The Old Bell" },
"data": { ... }
}
data holds the record in the same shape the API returns it, so a reservation payload looks like
a reservation from GET /reservations/{id}. One integration can handle both sources with the same
parsing code (link API reference).
What to key on
X-Tabledoo-Delivery-Id— for idempotency. Always.event— to route. Or theX-Tabledoo-Eventheader, which saves parsing the body first.- The record's
idinsidedata— your stable link to the booking, guest or order. It does not change. timestamp— to order events, since delivery order is not guaranteed.api_version— so a future version does not surprise you.
Do not key on field positions or assume the field list is fixed: new fields may be added, which is why your parser should ignore what it does not recognise rather than failing.
Monthly delivery allowance
Your plan sets how many webhook deliveries you get per calendar month. Reach it and further events are skipped for the rest of the month — silently, with no delivery record and no warning.
Two things follow:
- Subscribe only to events you act on. The cheapest way to stay inside the allowance.
- Watch out for high-volume events. On a busy QR-ordering night,
order.item.status_updatedcan fire many times per table. If you only need whole-ticket progress, subscribe toorder.status_updatedalone.
Your allowance is part of your plan (link Your plan and what it includes).
Good to know
Every active endpoint subscribed to an event gets its own delivery, each counting separately against the allowance.
Deactivated endpoints receive nothing and consume nothing.
Events are not held for later if your endpoint is down. Orders, waiter calls and incoming calls are retried
for under two minutes, everything else for about an hour; then they are abandoned and your staff are notified.
Recover a failed delivery with a manual retry (link
Delivery history and retries), or re-read what changed with
updated_since on the API list endpoints (link API reference).