Webhooks overview

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 for arrives within a second or so.

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.

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.

Keep the signing secret

You get back a signing secret, which is how you prove a delivery came from us. See Verifying signatures.

The envelope

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

{
  "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.