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

[
  {
    "admintoken": []
  }
]

{
  "admintoken": {
    "name": "admintoken",
    "type": "apiKey",
    "in": "header",
    "description": "Token de administrador para endpoints administrativos"
  }
}

Corpo da requisição

{
  "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

{
  "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

{
  "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 · Erros e retries · Server URL