Events
Every event arrives by webhook in the same envelope and
can be retrieved for 30 days with GET /v1/events/{id}. The list of what an
endpoint can subscribe to in your workspace is at GET /v1/event-types.
Envelope
Section titled “Envelope”Every webhook is a POST with Content-Type: application/json and this envelope:
{ "id": "evt_9b2f0c1d4e5a46b7a8c9d0e1f2a3b4c5", "type": "whatsapp.message.received", "created_at": "2026-11-16T15:04:05.123Z", "workspace_id": "6e0b1c2d-3e4f-4a5b-8c6d-7e8f9a0b1c2d", "data": { }}Headers (Standard Webhooks spec):
| Header | Value |
|---|---|
webhook-id |
The event id. It is the same on every attempt: use it to deduplicate. |
webhook-timestamp |
Unix seconds of this attempt. |
webhook-signature |
v1,<signature>; for 24 h after a secret rotation, two of them, separated by a space. |
whatsapp.message.received
Section titled “whatsapp.message.received”A message received on one of the workspace’s lines (from a lead or a contact).
{ "id": "evt_…", "type": "whatsapp.message.received", "created_at": "2026-11-16T15:04:05.123Z", "workspace_id": "6e0b1c2d-…", "data": { "id": "0d9c8b7a-6f5e-4d3c-8b2a-1f0e9d8c7b6a", "conversation_id": "5a4b3c2d-1e0f-4a9b-8c7d-6e5f4a3b2c1d", "direction": "inbound", "status": "received", "type": "text", "text": "Hi, I'd like to know the price", "from": "+5511999990000", "to": "+5511888880000", "media": null, "template": null, "lead_id": "7c6b5a49-3827-4615-9a8b-7c6d5e4f3a2b", "contact_id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "created_at": "2026-11-16T15:04:05.001Z" }}from is the contact and to is the line (E.164). With a file, type is image,
audio, video, document or sticker, and media carries { id, type, mime_type, file_name }
so you can download it through the WhatsApp API.
whatsapp.message.sent
Section titled “whatsapp.message.sent”A message was sent (accepted by the provider), from any source. Same fields,
with direction: "outbound", from = line, to = contact, plus:
| Field | Value |
|---|---|
origin |
api (your integration), cadence (a cadence step), ai (an AI reply), human (a person in Preflow) or whatsapp_app (the WhatsApp Business app on a phone). Same value as in the API’s message history. |
client_reference |
Only with origin: "api": the value you sent with the message |
api_message_id |
Only with origin: "api" |
A message the provider refused right away doesn’t trigger sent (the API send
call already responds with the error).
whatsapp.message.status_updated
Section titled “whatsapp.message.status_updated”A sent message was delivered, read or failed. Same fields as the message, plus:
{ "status": "failed", "previous_status": "sent", "status_at": "2026-11-16T15:05:00Z", "failure": { "reason": "window_closed" }}status: delivered, read or failed. Each status arrives once per message.
failure.reason (only on failed): window_closed (outside the 24-hour window, a
template is required), invalid_recipient, recipient_opted_out, not_delivered_by_whatsapp
(WhatsApp decided not to deliver it), rate_limited, template_error, media_error
or delivery_failed.
whatsapp.template.status_updated
Section titled “whatsapp.template.status_updated”{ "id": "2b3c4d5e-6f70-4a8b-9c0d-1e2f3a4b5c6d", "name": "boas_vindas", "language": "pt_BR", "category": "UTILITY", "provider": "meta", "status": "approved", "previous_status": "pending", "reason": null}status: approved, pending, rejected or archived.
webhook.test
Section titled “webhook.test”Sent by “Test” on the screen or by POST /v1/webhook-endpoints/{id}/test, only to
that endpoint: data = { "endpoint_id": "…", "message": "Evento de teste do Preflow." }.
Leads, accounts and meetings
Section titled “Leads, accounts and meetings”Each event’s data is a snapshot of the resource at the time of the event, in
the same format as the corresponding GET routes; use the id to fetch the
current state.
| Event | When | data |
|---|---|---|
lead.created |
A new lead in the workspace (from any source, not only the API) | { lead } |
inbound.submission_received |
A conversion recorded by POST /v1/inbound-submissions (new lead, existing lead or contact only) |
{ inbound_submission } |
lead.lost |
A lead was marked as lost | { lead, reason, reason_label, scope, lost_at } |
account.stage_changed |
The account changed stage in a funnel | { account, funnel_id, product_id, from_stage, to_stage, intermediate_stage, changed_at } |
account.qualification_changed |
The account’s qualification changed (e.g. it became Customer or Churn) | { account, from, to, changed_at } |
meeting.scheduled |
A meeting was booked | { meeting } |
meeting.rescheduled |
A meeting’s time changed | { meeting, previous_starts_at } |
meeting.cancelled, meeting.completed, meeting.no_show |
A meeting was cancelled, held or a no-show | { meeting } |
scopeonlead.lost:lead(only this person) orfunnel(the account leaves that funnel).- An account entering its first funnel doesn’t trigger
account.stage_changed:lead.createdalready covers it. - Blocks copied from Outlook or Google calendars don’t trigger meeting events, and
onboarding test leads don’t trigger
lead.created.
{ "id": "evt_…", "type": "account.stage_changed", "created_at": "2026-11-16T15:00:00.000Z", "workspace_id": "6c1f…", "data": { "account": { "id": "4007…", "object": "account", "name": "Acme", "qualification": "sql", "…": "…" }, "funnel_id": "0aff…", "product_id": null, "from_stage": "qualified", "to_stage": "scheduled", "intermediate_stage": null, "changed_at": "2026-11-16T14:59:58.120Z" }}