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 Ações, 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 vão no JSON enviado ao webhook. Cada campo tem um seletor que define quem preenche o valor:
- IA: o agente coleta o valor durante a conversa. Use para o que só aparece no diálogo, como a data desejada, o motivo do contato ou um resumo da qualificação.
- Fixo: a Wevichat preenche o valor com os dados que já tem do contato, sem passar pela IA. Use para nome, telefone, email, campos personalizados e identificadores do seu CRM.
Para um campo IA, configure:
- Chave: nome do campo no JSON enviado (ex:
data_consulta) - Label: nome legível para a IA (ex: "Data da consulta")
- Dica para a IA: formato ou regra do valor (ex: "Formato DD/MM/AAAA")
- Tipo: Texto, Número ou Sim/Não
- Obrigatório: se o agente deve garantir que o dado está disponível antes de acionar
Para um campo Fixo, configure a Chave e o Valor. O valor pode ser um texto qualquer ou uma variável. Clique no botão { } ao lado do campo para inserir a variável sem digitar.
| Variável | O que envia |
|---|---|
{{contact.name}} |
Nome do contato |
{{contact.phone}} |
Telefone |
{{contact.email}} |
|
{{contact.chave_do_campo}} |
Valor de um campo personalizado, pela chave (ex: {{contact.id_deal}}) |
{{contact.id}} |
Identificador do contato na Wevichat |
{{contact.stage}} e {{contact.pipeline}} |
Etapa e funil do contato |
{{contact.tags}} |
Etiquetas do contato, como lista |
{{contact.assigned_user.name}} |
Atendente responsável |
{{conversation.id}} e {{conversation.channel}} |
Identificador e canal da conversa |
{{now}} |
Data e hora do envio |
Quando o valor é só a variável, ela chega com o tipo original: um número continua número e as etiquetas chegam como lista. Misturada com texto (ex: Deal {{contact.id_deal}}), ela vira texto. Se o contato não tiver o dado, o campo vai vazio.
O agente só dispara o webhook quando tiver os campos IA obrigatórios. Os campos Fixo ficam de fora da conversa: a IA nem sabe que eles existem, então não gasta mensagens pedindo um dado que você já tem e não corre o risco de escrever o valor errado.
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
Evitar que a ação rode mais de uma vez
Algumas ações só fazem sentido uma vez por conversa, como enviar a qualificação do lead para o CRM ou abrir um ticket. Se o cliente manda um "obrigado" depois do encerramento, o agente não deve disparar tudo de novo.
O agente sabe quais ações já executou em cada conversa e se elas deram certo. Isso já evita a maior parte das repetições. Para ter a garantia, ligue a opção Executar no máximo uma vez por conversa na ação:
- Abra a ação em Ações do Agente e clique em editar.
- Ligue Executar no máximo uma vez por conversa.
- Clique em Salvar ação.
Com a opção ligada, depois que a ação roda com sucesso, ela deixa de estar disponível para o agente naquela conversa. Se a chamada der erro (o seu sistema fora do ar, por exemplo), o agente ainda pode tentar outra vez. Numa conversa nova, a ação volta a ficar disponível.
Na lista de ações, as que têm a trava ligada aparecem com a marcação 1x por conversa.
Deixe a opção desligada em ações que precisam rodar várias vezes, como consultar horários disponíveis ou buscar o status de um pedido.
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
Variáveis na URL e nos headers
A URL e os valores dos headers aceitam as mesmas variáveis dos campos fixos. Assim você chama o registro certo no seu sistema sem pedir nada à IA:
https://api.seucrm.com/deals/{{contact.id_deal}}
Na URL, o valor da variável é codificado automaticamente, então um nome com espaço ou acento não quebra o endereço.
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
Próximos passos
- Como integrar com Google Sheets →
- Como usar multi-agentes →
- Como interpretar o dashboard de analytics →
Veja também: Receber avisos de eventos, que é o caminho inverso. Em vez do agente chamar o seu sistema, a Wevichat avisa você quando algo acontece na plataforma.