Eventos
Todo evento chega por webhook com o mesmo envelope e
pode ser consultado por 30 dias em GET /v1/events/{id}. A lista do que um
endpoint pode assinar no seu workspace está em GET /v1/event-types.
Envelope
Seção intitulada “Envelope”Todo webhook é um POST com Content-Type: application/json e este envelope:
{ "id": "evt_9b2f0c1d4e5a46b7a8c9d0e1f2a3b4c5", "type": "whatsapp.message.received", "created_at": "2026-11-16T15:04:05.123Z", "workspace_id": "6e0b1c2d-3e4f-4a5b-8c6d-7e8f9a0b1c2d", "data": { }}Cabeçalhos (padrão Standard Webhooks):
| Cabeçalho | Valor |
|---|---|
webhook-id |
O id do evento. É o mesmo em todas as tentativas: use para deduplicar. |
webhook-timestamp |
Segundos Unix desta tentativa. |
webhook-signature |
v1,<assinatura>; durante 24 h depois de girar o segredo, duas, separadas por espaço. |
whatsapp.message.received
Seção intitulada “whatsapp.message.received”Mensagem recebida numa linha do workspace (do lead ou de um contato).
{ "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": "Oi, quero saber o preço", "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 é o contato e to é a linha (E.164). Com arquivo, type é image,
audio, video, document ou sticker e media traz { id, type, mime_type, file_name }
para baixar pela API de WhatsApp.
whatsapp.message.sent
Seção intitulada “whatsapp.message.sent”Mensagem enviada (aceita pelo provedor), de qualquer origem. Os mesmos campos,
com direction: "outbound", from = linha, to = contato, e:
| Campo | Valor |
|---|---|
origin |
api (sua integração), cadence (passo de cadência), ai (resposta da IA), human (pessoa no Preflow) ou whatsapp_app (app do WhatsApp Business do celular). O mesmo valor do histórico de mensagens da API. |
client_reference |
Só com origin: "api": o valor que você mandou no envio |
api_message_id |
Só com origin: "api" |
Mensagem que o provedor recusou na hora não gera sent (o envio pela API já
responde com o erro).
whatsapp.message.status_updated
Seção intitulada “whatsapp.message.status_updated”Mensagem enviada foi entregue, lida ou falhou. Os mesmos campos da mensagem e:
{ "status": "failed", "previous_status": "sent", "status_at": "2026-11-16T15:05:00Z", "failure": { "reason": "window_closed" }}status: delivered, read ou failed. Cada status chega uma vez por mensagem.
failure.reason (só em failed): window_closed (fora da janela de 24 h, precisa
de template), invalid_recipient, recipient_opted_out, not_delivered_by_whatsapp
(o WhatsApp decidiu não entregar), rate_limited, template_error, media_error
ou delivery_failed.
whatsapp.template.status_updated
Seção intitulada “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 ou archived.
webhook.test
Seção intitulada “webhook.test”Mandado por “Testar” na tela ou por POST /v1/webhook-endpoints/{id}/test, só para
aquele endpoint: data = { "endpoint_id": "…", "message": "Evento de teste do Preflow." }.
Leads, contas e reuniões
Seção intitulada “Leads, contas e reuniões”O
data de cada evento é a foto do recurso no momento do evento, no mesmo
formato das rotas GET acima; use o id para buscar o estado atual.
| Evento | Quando | data |
|---|---|---|
lead.created |
Lead novo no workspace (por qualquer entrada, não só a API) | { lead } |
inbound.submission_received |
Conversão registrada por POST /v1/inbound-submissions (lead novo, lead que já existia ou só contato) |
{ inbound_submission } |
lead.lost |
Lead marcado como perdido | { lead, reason, reason_label, scope, lost_at } |
account.stage_changed |
A conta mudou de etapa num funil | { account, funnel_id, product_id, from_stage, to_stage, intermediate_stage, changed_at } |
account.qualification_changed |
A qualificação da conta mudou (ex.: virou Cliente ou Churn) | { account, from, to, changed_at } |
meeting.scheduled |
Reunião marcada | { meeting } |
meeting.rescheduled |
Reunião mudou de horário | { meeting, previous_starts_at } |
meeting.cancelled, meeting.completed, meeting.no_show |
Reunião cancelada, realizada ou sem comparecimento | { meeting } |
scopedolead.lost:lead(só esta pessoa) oufunnel(a conta sai daquele funil).- A entrada da conta no primeiro funil não gera
account.stage_changed: olead.createdjá avisa. - Bloqueios copiados da agenda do Outlook ou do Google não geram evento de
reunião, e lead de teste do onboarding não gera
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": "Empresa", "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" }}