# Webhooks overview

> Signed HTTP callbacks the moment something happens, instead of polling the API

Source: https://www.hey.support/docs/developer-guide/webhooks

---

Webhooks push events to your own endpoint as they happen. A new lead, a booking, a visitor asking for a human: anything you would otherwise poll the [API](/docs/api) for arrives within a second or so.

## Set one up

<Steps>
  <Step>
    ### Add an endpoint

    Go to **Settings, Developer** (owners only) and add an endpoint. The URL must be `https` in production and must not resolve to a private or link-local address; we check on every delivery, not just when you save.
  </Step>

  <Step>
    ### Choose events and scope

    Subscribe only to the events you handle; unsubscribed events are never sent. An endpoint is either workspace-wide or scoped to a single agent.
  </Step>

  <Step>
    ### Keep the signing secret

    You get back a signing secret, which is how you prove a delivery came from us. See [Verifying signatures](/docs/developer-guide/webhooks/signature).
  </Step>
</Steps>

## The envelope

Every delivery is a JSON `POST` with the same outer shape. Only `data` varies by event.

```json
{
  "id": "3f1c…",
  "event_id": "b47e…",
  "event": "lead.created",
  "api_version": "2026-04-27",
  "created_at": "2026-08-26T10:00:00.000Z",
  "workspace_id": 42,
  "chatbot_id": 17,
  "data": {}
}
```

| Field         | Meaning                                                                                   |
| ------------- | ----------------------------------------------------------------------------------------- |
| `id`          | This delivery attempt. Stable across retries of the same attempt.                         |
| `event_id`    | The logical event. **Dedupe on this.** Shared across endpoints, different across resends. |
| `event`       | The event name, e.g. `lead.created`.                                                      |
| `api_version` | Payload contract version. Currently `2026-04-27`.                                         |
| `chatbot_id`  | Present when the event belongs to one agent.                                              |
| `data`        | The event-specific body.                                                                  |

## Headers

| Header                     | Purpose                                           |
| -------------------------- | ------------------------------------------------- |
| `X-HeySupport-Signature`   | HMAC-SHA256 of the raw body, as `sha256=<hex>`.   |
| `X-HeySupport-Delivery-Id` | Matches `id`. Unique per delivery attempt.        |
| `X-HeySupport-Event-Id`    | Matches `event_id`. Use it to dedupe.             |
| `X-HeySupport-Event`       | The event name, so you can route without parsing. |

## Events

<Cards>
  <IconCard icon="message-circle" title="Conversation events" href="/docs/developer-guide/webhooks/events/conversation" description="conversation.started, conversation.ended, message.sent" />

  <IconCard icon="user-round" title="Lead events" href="/docs/developer-guide/webhooks/events/lead" description="lead.created" />

  <IconCard icon="calendar-days" title="Booking events" href="/docs/developer-guide/webhooks/events/booking" description="booking.created, booking.rescheduled, booking.canceled" />

  <IconCard icon="calendar-check" title="Reservation events" href="/docs/developer-guide/webhooks/events/reservation" description="reservation.requested, reservation.created, reservation.updated, reservation.canceled" />

  <IconCard icon="hand" title="Handoff events" href="/docs/developer-guide/webhooks/events/handoff" description="handoff.requested, handoff.resolved" />

  <IconCard icon="zap" title="Action events" href="/docs/developer-guide/webhooks/events/action" description="action.requires_approval" />
</Cards>

<Callout>
  Delivery is **at-least-once**. The same event can arrive more than once, so make your handler idempotent on `event_id`. See [Delivery and retries](/docs/developer-guide/webhooks/delivery).
</Callout>

<NextSteps>
  <IconCard icon="key-round" title="Verifying signatures" href="/docs/developer-guide/webhooks/signature" description="Check the HMAC on the raw body before you act." />

  <IconCard icon="refresh-cw" title="Delivery and retries" href="/docs/developer-guide/webhooks/delivery" description="Timeouts, retries, and what marks an endpoint unhealthy." />
</NextSteps>