Webhooks e SSE
Configurar Webhook da Instância
/webhookA NOD guarda a URL e repassa os eventos com assinatura. Use o modo simples (sem
actionnemid). Veja Webhooks.
Autenticação: envie a chave da conexão no header token ou em Authorization: Bearer.
Gerencia a configuração de webhooks para receber eventos em tempo real da instância. Permite gerenciar múltiplos webhooks por instância através do campo ID e action.
🚀 Modo Simples (Recomendado)
Uso mais fácil - sem complexidade de IDs:
- Não inclua
actionnemidno payload - Gerencia automaticamente um único webhook por instância
- Cria novo ou atualiza o existente automaticamente
- Recomendado: Sempre use
"excludeMessages": ["wasSentByApi"]para evitar loops - Exemplo:
{"url": "https://meusite.com/webhook", "events": ["messages"], "excludeMessages": ["wasSentByApi"]}
🧪 Sites para Testes (ordenados por qualidade)
Para testar webhooks durante desenvolvimento:
- https://webhook.cool/ - ⭐ Melhor opção (sem rate limit, interface limpa)
- https://rbaskets.in/ - ⭐ Boa alternativa (confiável, baixo rate limit)
- https://webhook.site/ - ⚠️ Evitar se possível (rate limit agressivo)
⚙️ Modo Avançado (Para múltiplos webhooks)
Para usuários que precisam de múltiplos webhooks por instância:
💡 Dica: Mesmo precisando de múltiplos webhooks, considere usar addUrlEvents no modo simples. Um único webhook pode receber diferentes tipos de eventos em URLs específicas (ex: /webhook/message, /webhook/connection), eliminando a necessidade de múltiplos webhooks.
- Criar Novo Webhook:
- Use
action: "add" - Não inclua
idno payload - O sistema gera ID automaticamente
- Atualizar Webhook Existente:
- Use
action: "update" - Inclua o
iddo webhook no payload - Todos os campos serão atualizados
- Remover Webhook:
- Use
action: "delete" - Inclua apenas o
iddo webhook - Outros campos são ignorados
Eventos Disponíveis
connection: Alterações no estado da conexãohistory: Recebimento de histórico de mensagensmessages: Novas mensagens recebidasmessages_update: Atualizações em mensagens existentesnewsletter_messages: Novos posts/mensagens de canais do WhatsApp
Para views e reactions de canais, use a rota /newsletter/updates.
call: Eventos de chamadas VoIPcontacts: Atualizações na agenda de contatospresence: Alterações no status de presençagroups: Modificações em gruposlabels: Gerenciamento de etiquetaschats: Eventos de conversaschat_labels: Alterações em etiquetas de conversasblocks: Bloqueios/desbloqueios
Remover mensagens com base nos filtros:
wasSentByApi: Mensagens originadas pela API ⚠️ IMPORTANTE: Use sempre este filtro para evitar loops em automaçõeswasNotSentByApi: Mensagens não originadas pela APIfromMeYes: Mensagens enviadas pelo usuáriofromMeNo: Mensagens recebidas de terceirosisGroupYes: Mensagens em gruposisGroupNo: Mensagens em conversas individuais
💡 Prevenção de Loops: Se você tem automações que enviam mensagens via API, sempre inclua "excludeMessages": ["wasSentByApi"] no seu webhook. Caso prefira receber esses eventos, certifique-se de que sua automação detecta mensagens enviadas pela própria API para não criar loops infinitos.
Ações Suportadas:
add: Registrar novo webhookdelete: Remover webhook existente
Parâmetros de URL:
addUrlEvents(boolean): Quando ativo, adiciona o tipo do evento como path parameter na URL.
Exemplo: https://api.example.com/webhook/{evento}
addUrlTypesMessages(boolean): Quando ativo, adiciona o tipo da mensagem como path parameter na URL.
Exemplo: https://api.example.com/webhook/{tipo_mensagem}
Combinações de Parâmetros:
- Ambos ativos:
https://api.example.com/webhook/{evento}/{tipo_mensagem}
Exemplo real: https://api.example.com/webhook/message/conversation
- Apenas eventos:
https://api.example.com/webhook/message - Apenas tipos:
https://api.example.com/webhook/conversation
Notas Técnicas:
- Os parâmetros são adicionados na ordem: evento → tipo mensagem
- A URL deve ser configurada para aceitar esses parâmetros dinâmicos
- Funciona com qualquer combinação de eventos/mensagens
Corpo da requisição (JSON)
| Campo | Tipo | Descrição |
|---|---|---|
| id | string | ID único do webhook (necessário para update/delete) Exemplo: 123e4567-e89b-12d3-a456-426614174000 |
| enabled | boolean | Habilita/desabilita o webhook Exemplo: true |
| url* | string | URL para receber os eventos Exemplo: https://example.com/webhook |
| events | array<string> | Lista de eventos monitorados |
| excludeMessages | array<string> | Filtros para excluir tipos de mensagens |
| addUrlEvents | boolean | Adiciona o tipo do evento como parâmetro na URL.
Exemplo: false |
| addUrlTypesMessages | boolean | Adiciona o tipo da mensagem como parâmetro na URL.
Exemplo: false |
| action | string | Ação a ser executada:
Se não informado, opera no modo simples (único webhook) |
* obrigatório
Exemplos de corpo
Exemplo Modo Simples (Recomendado)
{
"enabled": true,
"url": "https://webhook.cool/example",
"events": [
"messages",
"newsletter_messages",
"connection"
],
"excludeMessages": [
"wasSentByApi"
]
}Modo Avançado - Criar Webhook
{
"action": "add",
"enabled": true,
"url": "https://api.exemplo.com/webhook",
"events": [
"messages",
"groups"
],
"excludeMessages": [
"wasSentByApi"
]
}Modo Simples com URLs Dinâmicas
{
"enabled": true,
"url": "https://webhook.cool/api",
"events": [
"messages",
"connection",
"groups"
],
"excludeMessages": [
"wasSentByApi"
],
"addUrlEvents": true
}Respostas
- 200Webhook configurado ou atualizado com sucesso
- 400Requisição inválida
- 401Token inválido ou não fornecido
- 500Erro interno do servidor
Experimente
Atenção: a chamada é real. Ela roda na sua conexão e pode enviar mensagem de verdade. A chave fica só nesta tela e some ao sair dela; nunca é guardada.