Como configurar webhooks personalizados
Nível: Avançado
Tempo de leitura: 6 min
Plano necessário: Todos os planos
O que são ações de agente
Ações são webhooks que o agente dispara automaticamente durante a conversa. Quando você configura uma ação, define uma URL externa que recebe os dados coletados pelo agente via HTTP.
Casos de uso típicos:
- Registrar lead qualificado no CRM (HubSpot, RD Station, Pipedrive)
- Abrir ticket de suporte no Zendesk ou Freshdesk
- Notificar sistema de pedidos quando o cliente confirmar uma compra
- Acionar automação no n8n ou Make
Como configurar
Passo 1: Obtenha a URL do sistema externo
Seu sistema de destino precisa fornecer uma URL de webhook onde vai receber os dados. Consulte a documentação do sistema que você usa.
Exemplo (HubSpot): https://api.hubapi.com/crm/v3/objects/contacts
Passo 2: Crie a ação no agente
- Abra o agente desejado
- Vá na aba Inteligência, seção Ações do Agente
- Clique em Nova ação
- Preencha:
- Nome de exibição: como o agente vai identificar essa ação (ex: "Registrar lead"). Use esse nome no prompt para referenciar a ação.
- Slug: identificador técnico, gerado automaticamente a partir do nome
- Descrição para a IA: explica ao agente quando e como usar a ação. Quanto mais específico, melhor.
- URL do Webhook: endpoint de destino
- Método: POST, GET, PUT, PATCH ou DELETE (geralmente POST)
- Headers HTTP: cabeçalhos de autenticação e content-type necessários
Passo 3: Defina os campos do payload
Em Campos do payload, adicione os dados que o agente deve coletar antes de disparar o webhook. Para cada campo, configure:
- Chave: nome do campo no JSON enviado (ex:
email) - Label: nome legível para o Claude (ex: "E-mail do cliente")
- Tipo: Texto, Número ou Sim/Não
- Obrigatório: se o agente deve garantir que o dado está disponível antes de acionar
O agente coleta esses valores durante a conversa e só dispara o webhook quando tiver o necessário.
Passo 4: Instrua o agente no prompt
No system prompt, instrua o agente quando usar a ação, referenciando pelo nome exato que você definiu:
REGISTRO NO CRM
Quando um lead for qualificado (demonstrou interesse + forneceu contato):
1. Acione a ação "Registrar lead" com os dados do cliente
2. Se o registro for bem-sucedido, confirme ao cliente que ele será contatado
3. Se houver erro, avise o time via Slack
Autenticação e segurança
Para APIs que exigem autenticação, configure os headers necessários na ação:
Authorization: Bearer SEU_TOKEN
Content-Type: application/json
Testando a ação
Use ferramentas como webhook.site para inspecionar os dados enviados antes de configurar o destino real.
- Crie um endpoint temporário no webhook.site
- Configure na Wevi como URL da ação
- Acione o agente e verifique o payload recebido
- Ajuste os campos se necessário
- Substitua pela URL real do sistema de destino