Pular para o conteúdo

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.

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.

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.

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

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.

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

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

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 }
  • scope do lead.lost: lead (só esta pessoa) ou funnel (a conta sai daquele funil).
  • A entrada da conta no primeiro funil não gera account.stage_changed: o lead.created já 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"
}
}