Webhooks

Os webhooks permitem enviar eventos em tempo real para qualquer endpoint externo. Use-os para sincronizar mensagens com seu CRM, acionar automações no n8n/Make/Zapier ou construir backends personalizados.

Criar uma Assinatura de Webhook

Abra sua Location

Vá para Dashboard → Locations e selecione a location que você deseja inscrever.

Abra as Configurações

Clique na aba Settings (Configurações) dessa location.

Criar assinatura

Role até a seção Webhooks e clique em Create subscription (Criar assinatura).

Preencha o formulário

Complete o diálogo Create subscription (veja os campos abaixo).

Salvar

Clique em Create subscription para salvar. Se “Enviar um ping de teste” estiver ativado, um evento fictício será enviado via POST ao seu endpoint para verificar se ele funciona.

Campos da Assinatura

Nome (obrigatório)

Um rótulo legível para que você possa identificar a assinatura depois (ex.: Sincronização CRM, Handler de Entrada n8n).

URL de Destino

O endpoint HTTPS que receberá os payloads dos eventos.

https://example.com/webhooks

Seu endpoint deve responder com um código de status 2xx. Respostas que não sejam 2xx são tratadas como falhas.

Selecionar eventos

Escolha exatamente quais eventos devem acionar um webhook. Você pode combinar canais em uma única assinatura.

Inbound (Entrada) - uma mensagem de WhatsApp é recebida
Outbound (Saída) - uma mensagem de WhatsApp é enviada

iMessage

Inbound (Entrada) - um iMessage é recebido
Outbound (Saída) - um iMessage é enviado

SMS

Inbound (Entrada) - um SMS é recebido
Outbound (Saída) - um SMS é enviado

Sistema

Message failed (Falha na mensagem) - uma mensagem não pôde ser entregue (use para lógica de novas tentativas ou alertas)

Enviar um ping de teste após a criação

Quando ativado, o sistema enviará via POST um evento fictício para sua URL de Destino imediatamente após a criação da assinatura. Use isso para confirmar que seu endpoint está acessível e que seu handler interpreta os payloads corretamente.

Deixe esta opção ativada na primeira assinatura que você criar para um novo endpoint.

O corpo do ping de teste é { "type": "test.ping" }. Ele não está envolvido no envelope descrito abaixo.

Formato de Entrega

Todo evento, exceto o ping de teste, é enviado via POST como JSON, envolvido neste envelope:

{
  "version": "1.0",
  "event": "whatsapp.inbound",
  "eventId": "3f9e2b8c-1a2d-4e3f-9b1a-2c3d4e5f6a7b",
  "timestamp": "2026-08-03T14:22:05.123Z",
  "locationId": "loc_2f9a41",
  "payload": { }
}

Campo	Tipo	Descrição
`version`	`string`	Sempre `"1.0"`.
`event`	`string`	O nome do evento, correspondente ao que você selecionou ao criar a assinatura.
`eventId`	`string`	ID único para esta entrega. Use-o para deduplicar eventos reenviados.
`timestamp`	`string` (ISO 8601)	Quando o evento foi despachado.
`locationId`	`string`	A location à qual o evento pertence.
`payload`	`object`	Dados específicos do evento. Veja Payloads dos Eventos abaixo.

Cabeçalhos

Content-Type: application/json
X-WA-Event-Id: <eventId>
X-WA-Timestamp: <unix timestamp, ms>

X-WA-Event-Id corresponde ao eventId no corpo.

Payloads dos Eventos

O objeto payload difere de acordo com o canal e o tipo de evento. message.media[].type é sempre um dos seguintes: image, video, audio, document, file, ou unknown.

Mensagens de entrada

whatsapp.inbound, imessage.inbound, sms.inbound - disparado quando um contato envia uma mensagem para um dos seus números conectados.

WhatsApp
iMessage
SMS

{
  "messageId": "wamid.HBgLMTU1NTk4NzY1NDMV...",
  "locationId": "loc_2f9a41",
  "device": { "number": "15551230000", "name": "Recepção" },
  "contact": { "id": "contact_7be31c", "name": "Jane Doe", "number": "15559876543" },
  "message": {
    "text": "Oi, meu pedido está pronto?",
    "media": [{ "url": "https://cdn.example.com/img.jpg", "type": "image" }]
  },
  "transcribedAudio": "Texto transcrito de uma nota de voz, quando presente"
}

{
  "messageId": "msg_9d41ab",
  "locationId": "loc_2f9a41",
  "device": { "number": "15551230000" },
  "contact": { "id": "contact_7be31c", "name": "Jane Doe", "number": "15559876543" },
  "message": { "text": "Estou a caminho, 5 min" },
  "meta": { "transcribedAudio": "Texto transcrito de uma nota de voz, quando presente" }
}

{
  "messageId": "msg_4e17cd",
  "locationId": "loc_2f9a41",
  "device": { "number": "15551230000" },
  "contact": { "id": "contact_7be31c", "name": "Jane Doe", "number": "15559876543" },
  "message": { "text": "Posso remarcar para sexta-feira?" }
}

Campo	Tipo	Notas
`messageId`	`string`	ID da mensagem do provedor.
`locationId`	`string`	A location à qual o evento pertence.
`device.number`	`string`	O número conectado que recebeu a mensagem.
`device.name`	`string`	Opcional.
`contact.id`	`string`	ID do contato no GHL, se o remetente já for um contato conhecido.
`contact.name`	`string`	Opcional.
`contact.number`	`string`	Número do remetente. Opcional no WhatsApp, onde um remetente pode ser identificado apenas pelo `lid`.
`contact.lid` / `contact.waUsername`	`string`	Somente WhatsApp. Campos de identidade opcionais, presentes quando o WhatsApp os envia.
`message.text`	`string`	Opcional. Ausente em mensagens só com mídia.
`message.media`	`array`	Cada item tem `url` e `type`. Pode estar ausente, ou ser um array vazio, quando não há mídia.
`transcribedAudio`	`string`	Transcrição de uma nota de voz, quando a transcrição está habilitada.
`ctwa`	`object`	Somente WhatsApp. Metadados de anúncio click-to-WhatsApp, presente apenas quando a conversa começou a partir de um anúncio do WhatsApp.

transcribedAudio fica no nível superior no WhatsApp, mas aninhado em meta.transcribedAudio no iMessage e SMS.

Mensagens de saída

whatsapp.outbound, imessage.outbound, sms.outbound - disparado quando uma mensagem é enviada de um número conectado, seja digitada no dispositivo ou enviada pelo CRM.

{
  "messageId": "wamid.HBgLMTU1NTk4NzY1NDMV...",
  "source": "crm",
  "contact": { "id": "contact_7be31c", "number": "15559876543" },
  "message": { "text": "Seu pedido está pronto para retirada!" },
  "device": { "number": "15551230000", "name": "Recepção", "instanceIndex": 0 },
  "locationId": "loc_2f9a41",
  "timestamp": "2026-08-03T14:25:10.500Z"
}

Campo	Tipo	Notas
`messageId`	`string`
`locationId`	`string`	A location à qual o evento pertence.
`source`	`string`	Como a mensagem foi enviada: `crm` (pelo CRM ou por uma automação), `device` (digitada no telefone/app conectado), `n8n`, ou `api`.
`contact.id`	`string`
`contact.number`	`string`
`contact.name`	`string`	Opcional. Geralmente ausente em envios iniciados pelo CRM.
`contact.lid` / `contact.waUsername`	`string`	Somente WhatsApp. Campos de identidade opcionais, iguais aos de entrada.
`message.text` / `message.media`		Mesma estrutura das mensagens de entrada.
`device.number`	`string`	O número conectado que enviou.
`device.name`	`string`	Opcional.
`device.instanceIndex`	`number`	Opcional. A instância conectada que enviou.
`timestamp`	`string` (ISO 8601)

Falha na mensagem

message.failed - disparado quando uma mensagem de saída em qualquer canal não pôde ser entregue após novas tentativas.

{
  "messageId": "msg_7c6b5a",
  "contactId": "contact_7be31c",
  "message": "Oi, dando um retorno sobre seu agendamento",
  "channelType": "whatsapp",
  "error": {
    "code": "109",
    "type": "WhatsAppFailure",
    "message": "Could not send the message. Please contact Custom Provider Support team"
  },
  "device": { "instanceIndex": 2, "phoneNumber": "15551230000" },
  "receiver": { "phoneNumber": "15559876543", "contactId": "contact_7be31c" },
  "locationId": "loc_2f9a41",
  "timestamp": "2026-08-03T14:30:00.000Z"
}

Campo	Tipo	Notas
`messageId`	`string`
`contactId`	`string`	Opcional.
`message`	`string`	Prévia opcional do corpo da mensagem que falhou ao enviar.
`channelType`	`"whatsapp"` \| `"imessage"` \| `"sms"`	Opcional.
`error.code` / `.type` / `.message`	`string`	Detalhes da falha.
`device.instanceIndex`	`number` \| `null`
`device.phoneNumber`	`string` \| `null`	O número conectado que tentou o envio.
`receiver.phoneNumber`	`string`	Número do destinatário.
`receiver.contactId`	`string`	Opcional.
`locationId`	`string`	A location à qual o evento pertence.
`timestamp`	`string` (ISO 8601)	Quando a falha foi registrada.

error.code indica por que o envio falhou. Veja Códigos de Erro para a lista completa e o que fazer em cada caso.

Novos códigos podem ser adicionados com o tempo, então trate códigos não reconhecidos como uma falha genérica em vez de assumir uma lista fixa.

Boas Práticas

Use uma assinatura por integração. Mantém os logs e a rotação simples.
Verifique com o ping de teste antes de confiar em uma assinatura em produção.
Retorne 2xx rapidamente - delegue o trabalho lento a uma fila em segundo plano no seu handler.
Seja idempotente. Webhooks podem ocasionalmente ser reentregues.
Delimite por canal. Não se inscreva em eventos que você não vai processar.

Gerenciando Assinaturas

Na seção Webhooks das Configurações da Location, você pode:

Ver todas as assinaturas ativas e a data de criação
Excluir uma assinatura de que você não precisa mais
Criar assinaturas adicionais para endpoints separados

Solução de Problemas

O ping de teste nunca chegou

Confirme que seu endpoint está acessível publicamente (sem localhost / IPs privados)
Verifique se ele aceita POST e retorna 2xx
Confira se regras de firewall/WAF não estão bloqueando o IP

Os eventos pararam de disparar

Certifique-se de que a assinatura não foi excluída
Confirme que a location ainda tem uma instância conectada para o canal
Verifique os logs do seu endpoint em busca de respostas 5xx (entregas com falha são retentadas algumas vezes e depois descartadas)

Eventos duplicados

Os webhooks têm entrega “pelo menos uma vez” (at-least-once). Use o eventId de nível superior (também enviado como o cabeçalho X-WA-Event-Id) para deduplicar do seu lado.

Início

Primeiros Passos

WhatsApp

iMessage

SMS

Múltiplas Instâncias

Segurança e Aquecimento

Recursos

Recursos de JS Personalizado

Automação

Integração Externa

Dados e Privacidade

Criar uma Assinatura de Webhook

Campos da Assinatura

Nome (obrigatório)

URL de Destino

Selecionar eventos

WhatsApp

iMessage

SMS

Sistema

Enviar um ping de teste após a criação

Formato de Entrega

Cabeçalhos

Payloads dos Eventos

Mensagens de entrada

Mensagens de saída

Falha na mensagem

Boas Práticas

Gerenciando Assinaturas

Solução de Problemas

​Criar uma Assinatura de Webhook

​Campos da Assinatura

​Nome (obrigatório)

​URL de Destino

​Selecionar eventos

​WhatsApp

​iMessage

​SMS

​Sistema

​Enviar um ping de teste após a criação

​Formato de Entrega

​Cabeçalhos

​Payloads dos Eventos

​Mensagens de entrada

​Mensagens de saída

​Falha na mensagem

​Boas Práticas

​Gerenciando Assinaturas

​Solução de Problemas

Criar uma Assinatura de Webhook

Campos da Assinatura

Nome (obrigatório)

URL de Destino

Selecionar eventos

WhatsApp

iMessage

SMS

Sistema

Enviar um ping de teste após a criação

Formato de Entrega

Cabeçalhos

Payloads dos Eventos

Mensagens de entrada

Mensagens de saída

Falha na mensagem

Boas Práticas

Gerenciando Assinaturas

Solução de Problemas