NODAPI

Webhooks e SSE

Configurar Webhook da Instância

POST/webhook
  • A NOD guarda a URL e repassa os eventos com assinatura. Use o modo simples (sem action nem id). 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 action nem id no 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:

  1. https://webhook.cool/ - ⭐ Melhor opção (sem rate limit, interface limpa)
  2. https://rbaskets.in/ - ⭐ Boa alternativa (confiável, baixo rate limit)
  3. 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.

  1. Criar Novo Webhook:
  • Use action: "add"
  • Não inclua id no payload
  • O sistema gera ID automaticamente
  1. Atualizar Webhook Existente:
  • Use action: "update"
  • Inclua o id do webhook no payload
  • Todos os campos serão atualizados
  1. Remover Webhook:
  • Use action: "delete"
  • Inclua apenas o id do webhook
  • Outros campos são ignorados

Eventos Disponíveis

  • connection: Alterações no estado da conexão
  • history: Recebimento de histórico de mensagens
  • messages: Novas mensagens recebidas
  • messages_update: Atualizações em mensagens existentes
  • newsletter_messages: Novos posts/mensagens de canais do WhatsApp

Para views e reactions de canais, use a rota /newsletter/updates.

  • call: Eventos de chamadas VoIP
  • contacts: Atualizações na agenda de contatos
  • presence: Alterações no status de presença
  • groups: Modificações em grupos
  • labels: Gerenciamento de etiquetas
  • chats: Eventos de conversas
  • chat_labels: Alterações em etiquetas de conversas
  • blocks: Bloqueios/desbloqueios

Remover mensagens com base nos filtros:

  • wasSentByApi: Mensagens originadas pela API ⚠️ IMPORTANTE: Use sempre este filtro para evitar loops em automações
  • wasNotSentByApi: Mensagens não originadas pela API
  • fromMeYes: Mensagens enviadas pelo usuário
  • fromMeNo: Mensagens recebidas de terceiros
  • isGroupYes: Mensagens em grupos
  • isGroupNo: 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 webhook
  • delete: 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:

  1. Os parâmetros são adicionados na ordem: evento → tipo mensagem
  2. A URL deve ser configurada para aceitar esses parâmetros dinâmicos
  3. Funciona com qualquer combinação de eventos/mensagens

Corpo da requisição (JSON)

CampoTipoDescrição
idstring

ID único do webhook (necessário para update/delete)

Exemplo: 123e4567-e89b-12d3-a456-426614174000

enabledboolean

Habilita/desabilita o webhook

Exemplo: true

url*string

URL para receber os eventos

Exemplo: https://example.com/webhook

eventsarray<string>

Lista de eventos monitorados

excludeMessagesarray<string>

Filtros para excluir tipos de mensagens

addUrlEventsboolean

Adiciona o tipo do evento como parâmetro na URL.

  • false (padrão): URL normal
  • true: Adiciona evento na URL (ex: /webhook/message)

Exemplo: false

addUrlTypesMessagesboolean

Adiciona o tipo da mensagem como parâmetro na URL.

  • false (padrão): URL normal
  • true: Adiciona tipo da mensagem (ex: /webhook/conversation)

Exemplo: false

actionstring

Ação a ser executada:

  • add: criar novo webhook
  • update: atualizar webhook existente (requer id)
  • delete: remover webhook (requer apenas id)

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.

Cole a chave gerada no painel.