O que sao webhooks e por que eles importam
Um webhook e uma chamada HTTP que o sistema faz automaticamente para um endereco externo quando um evento especifico ocorre. No contexto dos Agentes de IA do Z-PRO, o webhook permite que o agente acione acoes em sistemas externos durante a conversa com o cliente.
Isso abre um universo de possibilidades de integracao: consultar o status de um pedido em tempo real, criar uma oportunidade em um CRM externo, registrar um ticket de suporte, acionar um processo de aprovacao ou notificar uma equipe no Slack, tudo acionado automaticamente pela conversa no WhatsApp.
Como o webhook funciona no contexto do agente
Quando o agente identifica uma situacao que requer uma acao externa, ele dispara o webhook configurado, enviando as informacoes relevantes da conversa para o endpoint definido. O sistema externo processa a informacao e pode retornar uma resposta que o agente usa para formular a proxima mensagem ao cliente.
Por exemplo: o cliente pergunta sobre o status do pedido numero 12345. O agente dispara um webhook para o ERP da empresa enviando o numero do pedido. O ERP retorna o status atual. O agente usa essa informacao para responder ao cliente com o status real e atualizado.
Configurando um webhook na aba Ferramentas
Acesse o agente, va para a aba Ferramentas e adicione um novo webhook. Os campos basicos sao:
- Nome da ferramenta: um nome descritivo que o agente usara para decidir quando acionar. Por exemplo: Consultar status de pedido ou Criar ticket de suporte.
- Descricao: instrucao para o agente sobre quando usar esta ferramenta. Seja especifico: use esta ferramenta quando o cliente perguntar sobre o status de um pedido e fornecer um numero de pedido.
- URL do endpoint: o endereco HTTP que recebera a chamada.
- Metodo HTTP: GET ou POST, dependendo do que o sistema externo espera.
- Parametros: os dados que o agente vai enviar no corpo da requisicao ou na query string.
Passando dados da conversa para o webhook
O agente pode extrair informacoes da conversa e passa-las como parametros do webhook. Se o cliente informou o CPF durante a conversa, o agente consegue incluir esse CPF no payload do webhook. Isso e configurado nas instrucoes da ferramenta: voce especifica quais variaveis da conversa devem ser mapeadas para quais campos do payload.
Usando a resposta do webhook na conversa
Quando o endpoint retorna dados, o agente os recebe e pode usa-los para construir a resposta. Configure o endpoint para retornar um JSON estruturado com os campos que o agente deve usar. Nas instrucoes da ferramenta, indique como interpretar a resposta: se o campo status for entregue, informe ao cliente a data de entrega retornada no campo data_entrega.
Casos de uso mais comuns
- Consulta de pedidos: integrar com e-commerce ou ERP para checar status de pedidos em tempo real.
- Abertura de chamados: criar tickets automaticamente no sistema de suporte quando o cliente reporta um problema.
- Verificacao de cadastro: consultar se o cliente ja tem cadastro ativo antes de prosseguir com a conversa.
- Agendamento: verificar disponibilidade e criar compromissos em sistemas de agenda externos.
- Notificacoes internas: enviar alertas para canais do Slack ou Teams quando eventos importantes ocorrem na conversa.
Boas praticas de seguranca
Proteja seus endpoints de webhook. Use autenticacao por token no header da requisicao para garantir que apenas o Z-PRO consiga acionar seu endpoint. Valide o payload recebido antes de processar. Implemente um timeout curto no endpoint para evitar que o agente fique aguardando indefinidamente uma resposta que nao vai chegar.
