# Configurar Webhook Global POST /globalwebhook Configura um webhook global que receberá eventos de todas as instâncias. ### 🚀 Configuração Simples (Recomendada) **Para a maioria dos casos de uso**: - Configure apenas URL e eventos desejados - Modo simples por padrão (sem complexidade) - **Recomendado**: Sempre use `"excludeMessages": ["wasSentByApi"]` para evitar loops - **Exemplo**: `{"url": "https://webhook.cool/global", "events": ["messages", "connection"], "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) ### Funcionalidades Principais: - Configuração de URL para recebimento de eventos - Seleção granular de tipos de eventos - Filtragem avançada de mensagens - Parâmetros adicionais na URL **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 - `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 Globais**: O webhook global recebe eventos de TODAS as instâncias. Se você tem automações que enviam mensagens via API, sempre inclua `"excludeMessages": ["wasSentByApi"]`. 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 em múltiplas instâncias. **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 [ { "admintoken": [] } ] ``` ```json { "admintoken": { "name": "admintoken", "type": "apiKey", "in": "header", "description": "Token de administrador para endpoints administrativos" } } ``` ## Corpo da requisição ```json { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "URL para receber os eventos", "example": "https://webhook.cool/global" }, "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" ] }, "example": [ "messages", "connection" ] }, "excludeMessages": { "type": "array", "description": "Filtros para excluir tipos de mensagens", "items": { "type": "string", "enum": [ "wasSentByApi", "wasNotSentByApi", "fromMeYes", "fromMeNo", "isGroupYes", "isGroupNo" ] }, "example": [ "wasSentByApi" ] }, "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 } }, "required": [ "url", "events" ] }, "examples": { "configuracao_simples": { "summary": "Configuração Simples (Recomendada)", "description": "Configuração básica sem complexidade", "value": { "url": "https://webhook.cool/global", "events": [ "messages", "connection" ], "excludeMessages": [ "wasSentByApi" ] } }, "configuracao_completa": { "summary": "Configuração Completa", "description": "Exemplo com todos os recursos", "value": { "url": "https://webhook.cool/api", "events": [ "messages", "connection", "groups", "chats" ], "excludeMessages": [ "wasSentByApi", "isGroupNo" ], "addUrlEvents": true } } } } } } ``` ## Respostas ```json { "200": { "description": "Webhook global configurado com sucesso", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "400": { "description": "Payload inválido", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Invalid payload" } } } } } }, "401": { "description": "Token de administrador não fornecido", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Unauthorized" } } } } } }, "403": { "description": "Token de administrador inválido ou servidor demo", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "This is a public demo server. This endpoint has been disabled." } } } } } }, "500": { "description": "Erro interno do servidor", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Failed to save global webhook to database" } } } } } } } ``` ## #/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)