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:

Não inclua action nem id no payload.
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",
  "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",
  "events": ["messages"]
  // O sistema gera um ID automaticamente
}

{
  "action": "update",
  "id": "ID_DO_WEBHOOK", // Obrigatório
  "url": "https://api.site.com/nova-url",
  "events": ["messages", "call"]
}

{
  "action": "delete",
  "id": "ID_DO_WEBHOOK" // Apenas o ID é necessário
}

Eventos Disponíveis

Selecione quais tipos de notificação você deseja receber no array events.

Mensagens e Conversas

Evento	Descrição
`messages`	Novas mensagens recebidas.
`messages_update`	Atualização de status (entregue, lido) ou edição.
`history`	Recebimento do histórico de mensagens ao conectar.
`chats`	Eventos relacionados à lista de conversas.
`chat_labels`	Alterações em etiquetas de conversas.

Sistema e Conexão

Evento	Descrição
`connection`	Alterações no estado (QR Code, Conectado, Desconectado).
`presence`	Alterações no status de presença (online, digitando).
`contacts`	Atualizações na agenda de contatos.
`groups`	Modificações em grupos (título, participantes).
`blocks`	Bloqueios e desbloqueios de contatos.
`call`	Eventos de chamadas de voz/vídeo.

Marketing e Leads

Evento	Descrição
`leads`	Atualizações de leads.
`labels`	Gerenciamento de etiquetas.
`sender`	Atualizações de campanhas (início/término).

Filtros de Exclusão (`excludeMessages`)

Use o campo excludeMessages para ignorar mensagens específicas e economizar processamento.

Filtro	Descrição
`wasSentByApi`	Importante: Ignora mensagens enviadas pela própria API.
`wasNotSentByApi`	Ignora mensagens que NÃO foram enviadas pela API.
`fromMeYes`	Ignora mensagens enviadas pelo próprio usuário (celular).
`fromMeNo`	Ignora mensagens recebidas de outras pessoas.
`isGroupYes`	Ignora mensagens vindas de grupos.
`isGroupNo`	Ignora 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:

Apenas Eventos (addUrlEvents: true):
- https://api.example.com/webhook/message
- https://api.example.com/webhook/connection
Apenas Tipos (addUrlTypesMessages: true):
- https://api.example.com/webhook/conversation (texto)
- https://api.example.com/webhook/image (mídia)
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.

Primeiros Passos

Integrações

Configurar Webhook

Webhook da Instância

Ferramentas de Teste

Webhook.cool

SVIX

Webhook.site

Modo Simples (Recomendado)

Exemplo de Payload

Modo Avançado

Gerenciamento Manual

Eventos Disponíveis

Filtros de Exclusão (`excludeMessages`)

Parâmetros de URL (Rotas Dinâmicas)

Opções Disponíveis

addUrlEvents

addUrlTypesMessages

Exemplos de Resultados

​Webhook da Instância

​ Ferramentas de Teste

Webhook.cool

SVIX

Webhook.site

​ Modo Simples (Recomendado)

​Exemplo de Payload

​ Modo Avançado

​Gerenciamento Manual

​Eventos Disponíveis

​Filtros de Exclusão (excludeMessages)

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

​Opções Disponíveis

addUrlEvents

addUrlTypesMessages

​Exemplos de Resultados

Webhook da Instância

Ferramentas de Teste

Modo Simples (Recomendado)

Exemplo de Payload

Modo Avançado

Gerenciamento Manual

Eventos Disponíveis

Filtros de Exclusão (`excludeMessages`)

Parâmetros de URL (Rotas Dinâmicas)

Opções Disponíveis

Exemplos de Resultados