Configurar Webhooks no AgeuBot | Central de Ajuda

Webhooks sao notificacoes HTTP automaticas. Em vez de ficar perguntando "tem mensagem nova?" para a API a cada minuto, o AgeuBot te avisa no exato momento em que algo acontece, enviando um POST para a URL que voce configurar.

Quando usar webhooks

Use webhooks quando voce precisa reagir a eventos imediatamente:

Registrar cada nova conversa em um CRM proprio
Disparar um e-mail quando um lead entra em contato pelo WhatsApp
Alimentar um dashboard com mensagens em tempo real
Integrar com ferramentas de automacao (n8n, Make, Zapier)
Sincronizar status dos leads com outro sistema de vendas

Webhook ou API Publica? Webhooks sao "push" — o AgeuBot te avisa quando algo acontece. A API Publica e "pull" — voce consulta quando quiser. Use os dois juntos: webhooks para reagir a eventos, API para enviar mensagens e consultar dados sob demanda.

Como configurar

1 Prepare sua URL de recebimento

Voce precisa de um endpoint HTTP publico que aceite requisicoes POST com corpo JSON. Alguns jeitos de conseguir isso rapidamente:

Servidor proprio: um endpoint em Node.js, Python, PHP, Ruby etc.
n8n / Make / Zapier: crie um trigger "Webhook" e copie a URL gerada
Testar sem codigo: use webhook.site para inspecionar os payloads que o AgeuBot envia

Regras de seguranca aplicadas automaticamente ao salvar:

A URL deve usar HTTPS (HTTP puro e recusado)
Hostnames que resolvem para IPs privados ou internos (127.x, 10.x, 192.168.x, 172.16-31.x, 169.254.x) sao recusados
URL deve ter no maximo 2048 caracteres
Use certificado valido — Let's Encrypt funciona e e gratuito

2 Cadastre o webhook no painel

Passo a passo:

No painel do AgeuBot, va em Integracoes
Clique em Webhooks
Cole a URL do seu endpoint no campo URL de destino
Opcional: preencha Header de autenticacao — ex: Bearer seu_token_secreto
Marque os eventos que voce quer receber (veja lista abaixo)
Clique em Salvar e ative o toggle

Eventos disponiveis

Marque apenas os eventos que voce vai processar. Eventos extras so geram trafego desnecessario no seu servidor.

Evento	Quando dispara
message_received	Toda vez que um contato envia uma mensagem para o seu WhatsApp
message_sent	Toda vez que o AgeuBot (ou voce pelo painel) envia uma mensagem
contact_created	Quando um novo contato e criado no CRM (primeiro contato de um numero novo)
status_changed	Quando o status/etapa do lead muda no Kanban do CRM
chat_finished	Quando uma conversa e marcada como finalizada no painel
connection_status	Quando o status do WhatsApp muda (conectado, desconectado, reconectando)

Formato do payload

Toda requisicao enviada pelo AgeuBot segue o mesmo formato. O corpo e JSON:

{
  "event": "nome_do_evento",
  "data": { ... },
  "timestamp": "2026-04-22T14:00:00.000Z"
}

O campo data muda conforme o evento. Exemplos reais a seguir.

Exemplo: message_received

{
  "event": "message_received",
  "timestamp": "2026-04-22T14:00:00.000Z",
  "data": {
    "id": "uuid-interno...",
    "contact_jid": "5511999999999@s.whatsapp.net",
    "contact_name": "Joao Silva",
    "content": "Ola, quero saber sobre precos",
    "media_type": null,
    "media_url": null,
    "timestamp": "2026-04-22T14:00:00.000Z",
    "is_group": false,
    "participant_jid": null,
    "participant_name": null,
    "whatsapp_msg_id": "3EB0...",
    "session_id": "uuid-da-sessao"
  }
}

Exemplo: contact_created

{
  "event": "contact_created",
  "timestamp": "2026-04-22T14:00:00.000Z",
  "data": {
    "id": "uuid-interno...",
    "contact_jid": "5511999999999@s.whatsapp.net",
    "contact_name": "Joao Silva",
    "phone": "5511999999999",
    "session_id": "uuid-da-sessao",
    "lead_status": "novo",
    "source": "whatsapp",
    "created_at": "2026-04-22T14:00:00.000Z"
  }
}

Exemplo: status_changed

{
  "event": "status_changed",
  "timestamp": "2026-04-22T14:00:00.000Z",
  "data": {
    "contact_id": "uuid-interno...",
    "contact_jid": "5511999999999@s.whatsapp.net",
    "contact_name": "Joao Silva",
    "phone": "5511999999999",
    "new_status": "qualificado",
    "kanban_order": 3,
    "changed_at": "2026-04-22T14:00:00.000Z"
  }
}

Exemplo: connection_status

{
  "event": "connection_status",
  "timestamp": "2026-04-22T14:00:00.000Z",
  "data": {
    "status": "disconnected",
    "number": null,
    "sessionId": "uuid-da-sessao"
  }
}

Valores possiveis de status: connected, disconnected, logged_out. Quando connected, o campo number traz o numero do WhatsApp conectado.

Autenticando a origem do webhook

Qualquer um que descobrir sua URL poderia enviar dados falsos para ela. Para garantir que a requisicao veio do AgeuBot, configure um header de autenticacao:

No painel, em Integracoes > Webhooks, preencha o campo Header de autenticacao com algo como Bearer seu_token_secreto_aleatorio
No seu endpoint, verifique esse header em toda requisicao e rejeite (HTTP 401) se nao bater

Como gerar um token seguro? Use um gerador de senhas forte (ex: openssl rand -hex 32) e mantenha em uma variavel de ambiente no seu servidor. Nunca compartilhe ou exponha em repositorios publicos.

Exemplo de handler em Node.js

const express = require('express');
const app = express();
app.use(express.json());

const TOKEN = process.env.AGEUBOT_WEBHOOK_TOKEN;

app.post('/webhook/ageubot', (req, res) => {
  // 1. Validar origem
  if (req.headers.authorization !== `Bearer ${TOKEN}`) {
    return res.status(401).send('unauthorized');
  }

  // 2. Responder RAPIDO (idealmente < 1s)
  res.status(200).json({ ok: true });

  // 3. Processar em background, sem bloquear a resposta
  const { event, data } = req.body;
  switch (event) {
    case 'message_received':
      console.log('Nova mensagem de', data.contact_name, ':', data.content);
      // sua logica aqui
      break;
    case 'contact_created':
      console.log('Novo contato:', data.contact_name, data.phone);
      break;
    case 'status_changed':
      console.log('Status do', data.contact_name, 'mudou para', data.new_status);
      break;
  }
});

app.listen(3000, () => console.log('Webhook ouvindo na porta 3000'));

Exemplo em Python (Flask)

from flask import Flask, request, jsonify
import os

app = Flask(__name__)
TOKEN = os.environ['AGEUBOT_WEBHOOK_TOKEN']

@app.post('/webhook/ageubot')
def webhook():
    if request.headers.get('Authorization') != f'Bearer {TOKEN}':
        return 'unauthorized', 401

    payload = request.get_json()
    event = payload.get('event')
    data = payload.get('data', {})

    if event == 'message_received':
        print(f"Mensagem de {data.get('contact_name')}: {data.get('content')}")
    elif event == 'contact_created':
        print(f"Novo contato: {data.get('contact_name')}")

    return jsonify(ok=True), 200

if __name__ == '__main__':
    app.run(port=3000)

Boas praticas

Responda rapido (200 OK) assim que receber — o AgeuBot nao fica esperando sua logica processar. Se voce demorar muito ou cair, o webhook ainda assim "foi entregue"
Processe em background — use filas (BullMQ, RabbitMQ, Redis) para enfileirar os eventos e processar com calma
Valide o header de autenticacao SEMPRE — sem isso, qualquer um pode falsificar eventos
Guarde o whatsapp_msg_id para deduplicar: em casos raros de retry, voce pode receber o mesmo evento mais de uma vez
Filtre pelos eventos que voce realmente usa — cada evento gera 1 HTTP POST. Em uma conta com muitas mensagens, receber todos os eventos pode sobrecarregar seu servidor
Teste com webhook.site antes de subir para producao — assim voce ve os payloads reais e pode codar com base neles

Importante: O AgeuBot dispara webhooks em modo "fire and forget" com timeout de 10 segundos — se seu endpoint demorar mais que isso ou cair, o evento e abandonado (nao ha retry). Para eventos criticos, combine com consultas periodicas a API Publica como seguranca.

Problemas comuns

Meu webhook nao recebe nada

Confirme que o toggle da integracao esta ativo no painel
Confirme que a URL esta correta e acessivel publicamente pela internet (nao pode ser localhost ou IP privado)
Confirme que os eventos que voce quer receber estao marcados
Teste com webhook.site para isolar se o problema e no AgeuBot ou no seu servidor

Recebo eventos duplicados

Em casos raros, o mesmo evento pode chegar mais de uma vez. Use o campo id ou whatsapp_msg_id dentro de data como chave de deduplicacao

Meu servidor recebe e responde, mas o AgeuBot acha que falhou

Responda com HTTP 200 — qualquer outro status conta como falha
Nao demore mais que alguns segundos para responder — responda primeiro, processe depois

Recebo requisicoes em momentos estranhos

Provavelmente sao ataques de terceiros descobrindo sua URL. Por isso configure o header de autenticacao e rejeite qualquer requisicao sem ele com 401

Proximos passos

Precisa de ajuda para configurar seus webhooks? Fale com nosso suporte.

Falar com Suporte