Pular para o conteúdo

Webhooks — Payloads

Esta página mostra o que chega de fato no seu endpoint, evento por evento.

POST /seu-endpoint HTTP/1.1
Content-Type: application/json
Accept: 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.

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 id do topo é o id do recurso, não do evento. Dois eventos do mesmo contato trazem o mesmo id.
  • 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.

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.
  • messages traz 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_at vem com fração.
  • Quem é o cliente está em meta.sender; quem atende, em meta.assignee.
  • channel vem 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.

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_type separa 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.
  • sender muda de forma: quando é o cliente, é um contato; quando é atendente, vem "type": "user" com email junto.
  • attachments só aparece quando há anexo, com a URL de cada arquivo.
  • source_id é o identificador da mensagem no canal de origem — o wamid do WhatsApp, por exemplo. É o campo certo para casar com o sistema da outra ponta.

contact_created, contact_updated

{
"event": "contact_updated",
"id": 4521,
"name": "Maria Silva",
"email": "[email protected]",
"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": [
{ "email": { "previous_value": null, "current_value": "[email protected]" } }
]
}

contact_updated só dispara quando algo realmente mudou — se changed_attributes viria vazio, o evento não sai.

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",
"email": "[email protected]",
"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.

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

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.

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.

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.

Resposta suaResultado
Qualquer 2xxEntregue
Erro, recusa ou demora acima de 5 segundosRegistrado no nosso log e descartado

Não há reentrega. Veja entrega e falhas.

Sempre UTF-8. Acentos e emojis passam literais, sem entidade HTML escapada.