# Configurar Webhook da Instância POST /webhook 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 2. **Atualizar Webhook Existente**: - Use `action: "update"` - Inclua o `id` do webhook no payload - Todos os campos serão atualizados 3. **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 - `sender`: Atualizações de campanhas, quando inicia, e quando completa **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 ## Autenticação ```json [ { "token": [] } ] ``` ```json { "token": { "name": "token", "type": "apiKey", "in": "header" } } ``` ## Corpo da requisição ```json { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "ID único do webhook (necessário para update/delete)", "example": "123e4567-e89b-12d3-a456-426614174000" }, "enabled": { "type": "boolean", "description": "Habilita/desabilita o webhook", "example": true }, "url": { "type": "string", "description": "URL para receber os eventos", "example": "https://example.com/webhook" }, "events": { "type": "array", "description": "Lista de eventos monitorados", "items": { "type": "string", "enum": [ "connection", "history", "messages", "messages_update", "newsletter_messages", "call", "contacts", "presence", "groups", "labels", "chats", "chat_labels", "sender" ] } }, "excludeMessages": { "type": "array", "description": "Filtros para excluir tipos de mensagens", "items": { "type": "string", "enum": [ "wasSentByApi", "wasNotSentByApi", "fromMeYes", "fromMeNo", "isGroupYes", "isGroupNo" ] } }, "addUrlEvents": { "type": "boolean", "description": "Adiciona o tipo do evento como parâmetro na URL.\n- `false` (padrão): URL normal\n- `true`: Adiciona evento na URL (ex: `/webhook/message`)\n", "default": false }, "addUrlTypesMessages": { "type": "boolean", "description": "Adiciona o tipo da mensagem como parâmetro na URL.\n- `false` (padrão): URL normal \n- `true`: Adiciona tipo da mensagem (ex: `/webhook/conversation`)\n", "default": false }, "action": { "type": "string", "description": "Ação a ser executada:\n- add: criar novo webhook\n- update: atualizar webhook existente (requer id)\n- delete: remover webhook (requer apenas id)\nSe não informado, opera no modo simples (único webhook)\n", "enum": [ "add", "update", "delete" ] } }, "required": [ "url" ] }, "examples": { "modo_simples": { "summary": "Exemplo Modo Simples (Recomendado)", "description": "Configuração básica sem complexidade", "value": { "enabled": true, "url": "https://webhook.cool/example", "events": [ "messages", "newsletter_messages", "connection" ], "excludeMessages": [ "wasSentByApi" ] } }, "modo_avancado_criar": { "summary": "Modo Avançado - Criar Webhook", "description": "Criar novo webhook com ID automático", "value": { "action": "add", "enabled": true, "url": "https://api.exemplo.com/webhook", "events": [ "messages", "groups" ], "excludeMessages": [ "wasSentByApi" ] } }, "modo_simples_com_urls": { "summary": "Modo Simples com URLs Dinâmicas", "description": "Alternativa ao modo avançado usando addUrlEvents", "value": { "enabled": true, "url": "https://webhook.cool/api", "events": [ "messages", "connection", "groups" ], "excludeMessages": [ "wasSentByApi" ], "addUrlEvents": true } } } } } } ``` ## Respostas ```json { "200": { "description": "Webhook configurado ou atualizado com sucesso", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } } } } }, "400": { "description": "Requisição inválida", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Invalid action" } } } } } }, "401": { "description": "Token inválido ou não fornecido", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "missing token" } } } } } }, "500": { "description": "Erro interno do servidor", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Could not save webhook" } } } } } } } ``` ## #/components/schemas/Webhook ```json { "type": "object", "description": "Configuração completa de webhook com filtros e opções avançadas", "properties": { "id": { "type": "string", "description": "Identificador opaco gerado pelo servidor. Não presuma formato UUID." }, "enabled": { "type": "boolean", "description": "Webhook ativo/inativo", "default": false }, "url": { "type": "string", "format": "uri", "description": "URL de destino dos eventos" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "connection", "history", "messages", "messages_update", "newsletter_messages", "call", "contacts", "presence", "groups", "labels", "chats", "chat_labels", "sender" ] }, "description": "Tipos de eventos monitorados" }, "addUrlTypesMessages": { "type": "boolean", "description": "Incluir na URLs o tipo de mensagem", "default": false }, "addUrlEvents": { "type": "boolean", "description": "Incluir na URL o nome do evento", "default": false }, "excludeMessages": { "type": "array", "items": { "type": "string", "enum": [ "wasSentByApi", "wasNotSentByApi", "fromMeYes", "fromMeNo", "isGroupYes", "isGroupNo" ] }, "description": "Filtros para excluir tipos de mensagens" } }, "required": [ "url", "events" ], "example": { "id": "wh_9a8b7c6d5e", "enabled": true, "url": "https://webhook.cool/example", "events": [ "messages", "newsletter_messages", "connection" ], "addUrlTypesMessages": false, "addUrlEvents": false, "excludeMessages": [] } } ``` ## Guias relacionados [Autenticação](/docs/authentication) · [Erros e retries](/docs/errors-and-retries) · [Server URL](/docs/server-url)