Webhooks (n8n)

Cada agente pode ter eventos webhooks que disparam para sistemas externos quando algo acontece (mensagem recebida, conversa fechada, transferência humana, etc).

Eventos disponíveis

Evento	Quando dispara
message.received	Cliente mandou mensagem
message.sent	Agente respondeu
conversation.opened	Nova conversa criada
conversation.closed	Conversa fechada (auto ou manual)
human.transferred	Agente transferiu pra humano
intent.fired	Intenção detectada (antes do webhook da intent)

Cadastrar

POST /api/agents/{agentId}/webhooks
{
  "event": "human.transferred",
  "url": "https://n8n.vulkania.cloud/webhook/notify-team",
  "method": "POST",
  "headers": {
    "X-Source": "agentflow"
  }
}

Payload

{
  "event": "human.transferred",
  "timestamp": "2026-05-01T13:00:00.000Z",
  "agent": {
    "id": "agt_xyz",
    "name": "Carlos"
  },
  "conversation": {
    "id": "conv_abc",
    "contactName": "João Silva",
    "contactId": "5511999999999",
    "channel": { "type": "WHATSAPP", "label": "Bee 01" }
  },
  "data": {
    "transferSummary": "Cliente pedindo desconto fora da política. Encaminhar pra gerente."
  }
}

Retry

• 3 tentativas com backoff exponencial (1s, 4s, 16s)
• Após 3 falhas, marcamos webhook.lastError no DB e desistimos
• Sem dead-letter queue — depende de você monitorar via UI ou DB

Boas práticas

• Sempre responda 2xx rápido (< 5s). Para processamento longo, retorne 200 e processe async no n8n.
• Use X-Idempotency-Key (header enviado pelo AgentFlow com hash do evento) para dedupe.
• Whitelist o IP 72.60.14.189 no firewall do destino se for sistema interno.