# 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.

Source: https://tamr.link/docs/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](https://www.standardwebhooks.com) 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 be `http`, 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: false` and every id starting `test_`.

## What a delivery looks like

A delivery:

```http
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](https://tamr.link/docs/webhooks/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](https://tamr.link/docs/api/get-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`](https://tamr.link/docs/webhooks/order-placed) | A diner's order reached the restaurant's team | Tamr |
| [`order.cancelled`](https://tamr.link/docs/webhooks/order-cancelled) | An order you heard placed ended unserved | Tamr |
| [`payment.completed`](https://tamr.link/docs/webhooks/payment-completed) | Tamr Pay took a payment | Tamr |
| [`cart.proposed`](https://tamr.link/docs/webhooks/cart-proposed) | The waiter proposed lines to your app's cart | The app's cart |
| [`staff.requested`](https://tamr.link/docs/webhooks/staff-requested) | The waiter called staff | Either |
| [`booking.made`](https://tamr.link/docs/webhooks/booking-made) | The waiter booked a table | Either |
| [`booking.changed`](https://tamr.link/docs/webhooks/booking-changed) | The waiter moved or cancelled a booking | Either |
| [`review.submitted`](https://tamr.link/docs/webhooks/review-submitted) | A diner rated a dish of an order you sent | The app's cart |
| [`conversation.ended`](https://tamr.link/docs/webhooks/conversation-ended) | A chat ended | Either |
| [`menu.changed`](https://tamr.link/docs/webhooks/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](https://tamr.link/docs/guides/test-orders): 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](https://tamr.link/docs/api/erase-user) deletes the deliveries that named them.
