Pular para o conteúdo principal

​
Webhook da Instância

Gerencie a configuração para receber notificações de mensagens, conexões e outros eventos em tempo real no seu servidor.

​
🧪 Ferramentas de Teste

Antes de integrar, recomendamos testar o recebimento dos dados. Utilize uma dessas ferramentas para inspecionar o payload:

Webhook.cool

Recomendado. Sem rate limit e interface super limpa.

SVIX

Boa alternativa. Confiável e com baixo rate limit.

Webhook.site

Evite se possível. Possui rate limits muito agressivos.

​
🚀 Modo Simples (Recomendado)

Esta é a forma mais fácil de configurar. O sistema gerencia automaticamente um único webhook por instância, criando ou atualizando conforme necessário. Regras:
  1. Não inclua action nem id no payload.
  2. Sempre use filtros para evitar loops infinitos.
Prevenção de LoopsSe você utiliza automações, sempre inclua "excludeMessages": ["wasSentByApi"]. Isso impede que mensagens enviadas pelo seu próprio robô disparem novos eventos, criando um loop infinito.

​
Exemplo de Payload

{
  "url": "[https://meusite.com/webhook](https://meusite.com/webhook)",
  "events": [
    "messages",
    "connection"
  ],
  "excludeMessages": [
    "wasSentByApi"
  ]
}

​
⚙️ Modo Avançado

Utilize este modo apenas se precisar registrar múltiplos webhooks para a mesma instância (ex: um webhook para mensagens e outro para status de conexão).
Dica Pro: Mesmo precisando de múltiplos endpoints, considere usar o recurso de Parâmetros de URL (veja no final da página) com o Modo Simples. É mais fácil de manter.

​
Gerenciamento Manual

Para controlar múltiplos webhooks, você deve enviar o campo action. 
{
  "action": "add",
  "url": "[https://api.site.com/webhook-1](https://api.site.com/webhook-1)",
  "events": ["messages"]
  // O sistema gera um ID automaticamente
}

​
Eventos Disponíveis

Selecione quais tipos de notificação você deseja receber no array events.
EventoDescrição
messagesNovas mensagens recebidas.
messages_updateAtualização de status (entregue, lido) ou edição.
historyRecebimento do histórico de mensagens ao conectar.
chatsEventos relacionados à lista de conversas.
chat_labelsAlterações em etiquetas de conversas.
EventoDescrição
connectionAlterações no estado (QR Code, Conectado, Desconectado).
presenceAlterações no status de presença (online, digitando).
contactsAtualizações na agenda de contatos.
groupsModificações em grupos (título, participantes).
blocksBloqueios e desbloqueios de contatos.
callEventos de chamadas de voz/vídeo.
EventoDescrição
leadsAtualizações de leads.
labelsGerenciamento de etiquetas.
senderAtualizações de campanhas (início/término).

​
Filtros de Exclusão (excludeMessages)

Use o campo excludeMessages para ignorar mensagens específicas e economizar processamento.
FiltroDescrição
wasSentByApiImportante: Ignora mensagens enviadas pela própria API.
wasNotSentByApiIgnora mensagens que NÃO foram enviadas pela API.
fromMeYesIgnora mensagens enviadas pelo próprio usuário (celular).
fromMeNoIgnora mensagens recebidas de outras pessoas.
isGroupYesIgnora mensagens vindas de grupos.
isGroupNoIgnora mensagens de conversas privadas (PV).

​
Parâmetros de URL (Rotas Dinâmicas)

Você pode fazer com que a API adicione informações diretamente na URL do seu webhook, facilitando o roteamento no seu backend (ex: usar Node.js/Express ou Laravel Routes).

​
Opções Disponíveis

addUrlEvents

Adiciona o evento na URL. .../webhook/{evento}

addUrlTypesMessages

Adiciona o tipo da mensagem na URL. .../webhook/{tipo}

​
Exemplos de Resultados

Suponha que sua URL base seja https://api.example.com/webhook:
  1. Apenas Eventos (addUrlEvents: true):
    • https://api.example.com/webhook/message
    • https://api.example.com/webhook/connection
  2. Apenas Tipos (addUrlTypesMessages: true):
    • https://api.example.com/webhook/conversation (texto)
    • https://api.example.com/webhook/image (mídia)
  3. Ambos Ativos (Combinação): A ordem é sempre: {URL_BASE}/{EVENTO}/{TIPO_MENSAGEM}
    • https://api.example.com/webhook/message/conversation
    • https://api.example.com/webhook/message/audio
Certifique-se de que seu backend esteja configurado para aceitar parâmetros dinâmicos (wildcards) na rota para processar essas URLs corretamente.