Webhooks — Payloads
Esta página mostra o que chega de fato no seu endpoint, evento por evento.
Headers da requisição
Seção intitulada “Headers da requisição”POST /seu-endpoint HTTP/1.1Content-Type: application/jsonAccept: application/jsonÉ isso. Dois headers. Não há User-Agent próprio, nem header de assinatura, nem id de evento, nem id de entrega, nem id da conta.
O que todo payload tem
Seção intitulada “O que todo payload tem”Não existe um envelope comum com id e created_at do evento. O corpo é o objeto do recurso, com o campo event acrescentado:
{ "event": "contact_created", "id": 4521, "name": "Maria Silva", "...": "resto dos campos do contato"}Duas consequências práticas:
- O
iddo topo é o id do recurso, não do evento. Dois eventos do mesmo contato trazem o mesmoid. - Não há chave de idempotência pronta. Monte a sua a partir de
event+id+ o carimbo de tempo que vier no recurso.
Os eventos de mudança (conversation_updated, conversation_status_changed, contact_updated, inbox_updated) trazem ainda changed_attributes, com o antes e o depois do que mudou. Nesses casos, é ele que diz por que o evento disparou.
Conversas
Seção intitulada “Conversas”conversation_created, conversation_updated, conversation_status_changed
{ "event": "conversation_created", "id": 8821, "inbox_id": 5, "status": "open", "channel": "Channel::Whatsapp", "can_reply": true, "priority": null, "labels": ["orcamento"], "custom_attributes": {}, "additional_attributes": {}, "snoozed_until": null, "unread_count": 1, "first_reply_created_at": null, "waiting_since": 1758542400, "bot_active": true, "is_group": false, "group_jid": null, "contact_inbox": { "source_id": "5531988887777" }, "messages": [ { "id": 99012, "content": "Oi, queria um orçamento" } ], "meta": { "sender": { "id": 4521, "name": "Maria Silva" }, "assignee": { "id": 7, "name": "João Souza" }, "assignee_type": "User", "team": null, "hmac_verified": false }, "created_at": 1758542400, "updated_at": 1758542400.0, "last_activity_at": 1758542400, "timestamp": 1758542400}Pontos que pegam quem está lendo pela primeira vez:
idé o número da conversa na conta (o que aparece na URL), não a chave interna.messagestraz só a última mensagem do fio, não o histórico.- As datas são números — segundos desde 1970 —, não texto ISO.
updated_atvem com fração. - Quem é o cliente está em
meta.sender; quem atende, emmeta.assignee. channelvem com o nome interno da classe:Channel::Whatsapp,Channel::WebWidget,Channel::FacebookPage,Channel::Email.
Em conversation_status_changed, o status já vem com o valor novo; changed_attributes diz qual era o anterior.
Mensagens
Seção intitulada “Mensagens”message_created, message_updated
{ "event": "message_created", "id": 99012, "content": "Oi, queria um orçamento", "content_type": "text", "content_attributes": {}, "message_type": "incoming", "private": false, "source_id": "wamid.HBgNNTUzMT...", "created_at": "2026-09-22T14:30:00.000Z", "account": { "id": 1, "name": "Suaempresa" }, "inbox": { "id": 5, "name": "WhatsApp Comercial" }, "conversation": { "...": "o objeto de conversa acima, inteiro" }, "sender": { "id": 4521, "name": "Maria Silva", "email": null, "phone_number": "+5531988887777", "identifier": null, "custom_attributes": {}, "avatar": "", "thumbnail": "", "blocked": false, "account": { "id": 1, "name": "Suaempresa" }, "additional_attributes": {} }, "attachments": []}message_typesepara os sentidos:incomingé o cliente falando,outgoingé a equipe respondendo,templateé disparo de modelo,activityé evento de sistema.private: trueé nota interna — não foi visto pelo cliente. Quase sempre você quer ignorar.sendermuda de forma: quando é o cliente, é um contato; quando é atendente, vem"type": "user"comemailjunto.attachmentssó aparece quando há anexo, com a URL de cada arquivo.source_idé o identificador da mensagem no canal de origem — owamiddo WhatsApp, por exemplo. É o campo certo para casar com o sistema da outra ponta.
Contatos
Seção intitulada “Contatos”contact_created, contact_updated
{ "event": "contact_updated", "id": 4521, "name": "Maria Silva", "phone_number": "+5531988887777", "identifier": "CRM-4521", "avatar": "https://.../avatar.png", "thumbnail": "https://.../avatar.png", "blocked": false, "custom_attributes": { "cnpj": "12.345.678/0001-90" }, "additional_attributes": { "city": "Belo Horizonte" }, "account": { "id": 1, "name": "Suaempresa" }, "changed_attributes": [ ]}contact_updated só dispara quando algo realmente mudou — se changed_attributes viria vazio, o evento não sai.
Conversão
Seção intitulada “Conversão”conversion_event_created — o mais útil para marketing, e o único que só se assina pela API.
{ "event": "conversion_event_created", "id": 4521, "name": "Maria Silva", "phone_number": "+5531988887777", "custom_attributes": {}, "account": { "id": 1, "name": "Suaempresa" }, "conversion_identifier": "form-orcamento", "activity": { "id": 77120, "activity_type": "form_submission", "source_identifier": "form-orcamento", "properties": { "utm_source": "google", "utm_medium": "cpc", "utm_campaign": "institucional", "landing_page": "https://seusite.com.br/orcamento" }, "occurred_at": "2026-09-22T14:30:00.000Z" }}O corpo é o contato, com a conversão pendurada em activity. É ali que está a origem — UTMs, página, identificador do formulário. Veja eventos de conversão.
Chat do site
Seção intitulada “Chat do site”webwidget_triggered — o visitante abriu o chat.
{ "event": "webwidget_triggered", "id": 331, "source_id": "a1b2c3d4-...", "contact": { "id": 4521, "name": "Visitante" }, "inbox": { "id": 9, "name": "Site" }, "account": { "id": 1, "name": "Suaempresa" }, "current_conversation": { "...": "conversa em aberto, se houver" }, "event_info": { "browser": {}, "referer": "https://seusite.com.br/precos", "widget_language": "pt_BR" }}Caixas de entrada
Seção intitulada “Caixas de entrada”inbox_created, inbox_updated — também só pela API.
Trazem a configuração da caixa: horário de atendimento, distribuição automática, mensagem de saudação, pesquisa de satisfação, nome do remetente. Servem para sincronizar configuração, não para acompanhar atendimento.
Digitação
Seção intitulada “Digitação”conversation_typing_on, conversation_typing_off — o único payload com formato próprio:
{ "event": "conversation_typing_on", "user": { "id": 7, "name": "João Souza", "email": "joao@...", "type": "user" }, "conversation": { "...": "o objeto de conversa" }, "is_private": false}Só fazem sentido para quem está construindo uma interface de atendimento própria. Em operação com volume, são os eventos mais barulhentos que existem.
Ler sem quebrar
Seção intitulada “Ler sem quebrar”Trate campo ausente como normal. O payload monta o que existe naquele momento: attachments só aparece com anexo, changed_attributes só nos eventos de mudança, assignee é null em conversa sem responsável. Use leitura com valor padrão em tudo.
Não confie na ordem. Eventos próximos no tempo podem chegar trocados. Se a ordem importa, compare o carimbo de tempo do recurso antes de gravar:
def processar(evento): atual = buscar(evento['id']) if atual and atual.atualizado_em > evento.get('updated_at', 0): return # chegou atrasado, ignora gravar(evento)Ou desenhe para que a ordem não importe: grave o estado inteiro que veio, em vez de aplicar diferenças.
Confirme pela API quando a decisão for séria. O payload é um retrato do instante em que o evento saiu, e chega sem assinatura. Para agir com consequência, busque o dado pela API.
Entrega
Seção intitulada “Entrega”| Resposta sua | Resultado |
|---|---|
Qualquer 2xx | Entregue |
| Erro, recusa ou demora acima de 5 segundos | Registrado no nosso log e descartado |
Não há reentrega. Veja entrega e falhas.
Codificação
Seção intitulada “Codificação”Sempre UTF-8. Acentos e emojis passam literais, sem entidade HTML escapada.