# Reservation events

> reservation.requested, reservation.created, reservation.updated and reservation.canceled.

Source: https://www.hey.support/docs/webhooks/events/reservation

---

Reservations are tables, appointments and booking requests your agent takes for a venue — a separate module from [meeting bookings](/docs/webhooks/events/booking), which live on a Google Calendar. All four events carry the same `reservation` object; `reservation.updated` adds a `change` field saying what happened.

## The reservation object

```json
{
  "reservation": {
    "id": "0f4d2c2e-8a1b-4c3d-9e5f-6a7b8c9d0e1f",
    "chatbot_id": 17,
    "conversation_id": 8214,
    "customer_id": 42,
    "status": "confirmed",
    "service_id": 3,
    "service_name": "Dinner",
    "resource_id": 5,
    "resource_name": "Dining room",
    "start_at": "2026-10-02T18:00:00.000Z",
    "end_at": "2026-10-02T20:00:00.000Z",
    "party_size": 4,
    "name": "Ada Lovelace",
    "email": "ada@example.com",
    "phone": null,
    "answers": { "occasion": "Birthday" },
    "notes": "Window table if possible",
    "source": "card",
    "channel": null,
    "language": "en",
    "attendee_timezone": "Europe/Dublin",
    "cancel_reason": null,
    "cancelled_by": null,
    "decline_reason": null,
    "reschedule_count": 0,
    "created_at": "2026-09-26T10:05:00.000Z",
    "updated_at": "2026-09-26T10:05:00.000Z"
  }
}
```

| Field                 | Notes                                                                                                                                                                |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                  | A UUID, stable for the life of the reservation — a move or a status change never mints a new one.                                                                    |
| `status`              | `requested`, `confirmed`, `arrived`, `completed`, `no_show`, `cancelled` or `declined`.                                                                              |
| `start_at` / `end_at` | UTC. Use `attendee_timezone` to render the guest's local time; the venue's own zone is in its settings.                                                              |
| `party_size`          | People, for tables. `1` for an appointment.                                                                                                                          |
| `answers`             | The service's custom questions, keyed by question id.                                                                                                                |
| `source`              | `agent` (booked in conversation), `card` (the widget's card), `manual` (the calendar), `manage` (the guest's manage link), `api`, `channel` (Telegram and the like). |
| `cancelled_by`        | `customer`, `staff` or `system` on a cancelled reservation.                                                                                                          |

## `reservation.requested`

Fires when a reservation lands as a **request** — the service needs manual approval, or the party is over the online limit. The time is held on the calendar until the team answers; nothing is confirmed yet.

## `reservation.created`

Fires when a reservation is confirmed on the spot.

## `reservation.updated`

One event for every change to a live reservation. `change` says which, and the previous value rides beside it so you can update a record rather than guess:

```json
{
  "reservation": { "…": "…" },
  "change": "rescheduled",
  "previous_start_at": "2026-10-01T18:00:00.000Z"
}
```

| `change`      | Extra field                    | Meaning                                                                         |
| ------------- | ------------------------------ | ------------------------------------------------------------------------------- |
| `approved`    | `previous_status: "requested"` | The team approved a request; `status` is now `confirmed`.                       |
| `declined`    | `previous_status: "requested"` | The team declined a request; `reservation.decline_reason` may say why.          |
| `rescheduled` | `previous_start_at`            | The reservation moved. `reschedule_count` is bumped.                            |
| `status`      | `previous_status`              | A desk action: the guest arrived, the visit completed, or a no-show was marked. |

## `reservation.canceled`

Adds the reason, when one was given. `reservation.cancelled_by` says whether the guest, the team or the system cancelled:

```json
{
  "reservation": { "…": "…" },
  "cancel_reason": "Change of plans."
}
```