Webhooks
Tamr webhooks tell your backend what happened in your app's AI waiter chats and on the restaurant's menus: orders placed and cancelled, payments, bookings, staff calls, reviews, chats ending and menu changes, signed per Standard Webhooks.
Webhooks are signed HTTP calls Tamr makes to your server when something happens in your app's chats: an order is placed or cancelled, a payment completes, the waiter books a table or calls staff, a diner rates a dish, a chat ends. They are the source of truth for your backend. The events your app hears from the SDK are only for its screen.
Every delivery follows the Standard Webhooks specification, so any of its receiver libraries can check it.
Add an endpoint
A restaurant admin adds endpoints in Settings > App keys > Webhooks, choosing which events each one takes. The signing secret (whsec_…) is shown once, when the endpoint is added.
- Live endpoints get the events of live keys and must be
https. - Test endpoints get the events of test keys, with
livemode: false, and may behttp, for a tunnel to your machine. Neither gets the other's events. - At most 10 endpoints per restaurant. Addresses on a private network are refused.
- Rotate secret makes a new secret. For 24 hours every delivery is signed with both, so you can switch without missing an event.
- Deliveries shows each endpoint's last 30 days, with the body sent, the last answer, and Retry.
- Send a test event sends a sample of any type, with
livemode: falseand every id startingtest_.
What a delivery looks like
POST /tamr/webhooks HTTP/1.1
content-type: application/json
user-agent: Tamr-Webhooks/1.0
webhook-id: msg_8c2f8f4e-1d0b-4b8e-9d55-3a1f0a2b7c11
webhook-timestamp: 1793644930
webhook-signature: v1,<base64 HMAC-SHA256>
{"type":"staff.requested","timestamp":"2026-11-02T19:42:10.000Z","livemode":true,"data":{…}}| Part | What it is |
|---|---|
webhook-id | The event's id, the same on every retry of it. Handle each id once. |
webhook-timestamp | Seconds since 1970 when this attempt was sent. |
webhook-signature | v1, and the base64 HMAC-SHA256 of {webhook-id}.{webhook-timestamp}.{body}. See Verify signatures. |
type | The event, such as order.placed. |
timestamp | When it happened, ISO 8601. |
livemode | false for a test key's events and for test events sent from the dashboard. |
data | The event's payload. Each event's page lists its fields. |
Payloads carry ids, codes and amounts only. No message text, nothing the diner typed, no names, phone numbers or emails. Find your own product by externalId, or by dishId in Get the menu. New fields and new event types may appear in v1: ignore what you don't know.
The events
| Event | When | Orders go to |
|---|---|---|
order.placed | A diner's order reached the restaurant's team | Tamr |
order.cancelled | An order you heard placed ended unserved | Tamr |
payment.completed | Tamr Pay took a payment | Tamr |
cart.proposed | The waiter proposed lines to your app's cart | The app's cart |
staff.requested | The waiter called staff | Either |
booking.made | The waiter booked a table | Either |
booking.changed | The waiter moved or cancelled a booking | Either |
review.submitted | A diner rated a dish of an order you sent | The app's cart |
conversation.ended | A chat ended | Either |
menu.changed | A menu, its prices or your product ids changed | Either |
Test mode
A test key's chats send their events to your test endpoints only, with livemode: false. A test key's pickup is a test order: your test endpoint gets order.placed with test: true and an orderId that starts test_, and the restaurant gets nothing. Dine-in orders, payments and bookings need a live key; use Send a test event to see those payloads.
Deliveries are kept for 30 days. Erasing a user deletes the deliveries that named them.