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

[
  {
    "token": []
  }
]

{
  "token": {
    "name": "token",
    "type": "apiKey",
    "in": "header"
  }
}

Corpo da requisição

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

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

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