Skip to content

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.

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.

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.

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

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.

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

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

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 }
  • scope on lead.lost: lead (only this person) or funnel (the account leaves that funnel).
  • An account entering its first funnel doesn’t trigger account.stage_changed: lead.created already 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"
}
}