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](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
}

{
  "action": "update",
  "id": "ID_DO_WEBHOOK", // Obrigatório
  "url": "[https://api.site.com/nova-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

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