Webhooks de saída (integrar seu sistema)

Um webhook de saída é um endereço do seu sistema que a plataforma chama toda vez que algo acontece na conversa. É assim que você grava o atendimento inteiro no seu próprio banco de dados — por exemplo, num SaaS de Ordem de Serviço.

Cadastrar o destino

Os eventos

O que chega no seu sistema

A plataforma faz um POST com JSON e três cabeçalhos:

POST /seu/endpoint HTTP/1.1
Content-Type: application/json
X-Gateway-Event: conversation.inbound
X-Gateway-Event-Id: 5b7c1f8d-8c3f-4a2c-8a1b-123456789abc
X-Gateway-Signature: sha256=ASSINATURA_EM_HEXADECIMAL

O corpo sempre traz o mesmo envelope: event_id, event_type, source, org_id, agent_id, conversation_id, created_at e o payload do evento.

Exemplo de conversation.handoff (a conversa acabou de ser entregue a uma pessoa):

{
  "event_id": "5b7c1f8d-8c3f-4a2c-8a1b-123456789abc",
  "event_type": "conversation.handoff",
  "source": "hermes",
  "org_id": "<ID_DA_ORG>",
  "agent_id": "<ID_DO_AGENT>",
  "conversation_id": "5511999999999@s.whatsapp.net",
  "created_at": "2026-09-10T13:45:10.000Z",
  "payload": {
    "by": "agent:<ID_DO_AGENT>",
    "provider": "uazapi",
    "label": "atendimento humano",
    "label_status": "applied",
    "reason": "cliente pediu para falar com uma pessoa"
  }
}

by diz quem entregou: agent:<id> quando foi o próprio agent, ou a credencial que chamou a API de pausa. label_status vale applied, not_found (a etiqueta não existe na conta), not_supported (canal sem etiqueta, ou nenhuma pedida) ou failed. Numa pausa pela API, label e reason vêm null.

Validar a assinatura (obrigatório)

A assinatura é um HMAC SHA-256 do corpo bruto da requisição, usando o seu secret. Valide antes de interpretar ou salvar qualquer coisa — sem isso, qualquer um que descubra a sua URL consegue gravar dados falsos no seu sistema.

Exemplo genérico em Node.js:

import { createHmac, timingSafeEqual } from "node:crypto";
 
// SEU_SECRET vem do seu cofre de segredos — nunca escrito no código.
const secret = process.env.GATEWAY_WEBHOOK_SECRET;
 
export async function receberWebhook(request) {
  const corpoBruto = await request.text();       // o corpo CRU, antes de qualquer parse
  const recebida = request.headers.get("x-gateway-signature") ?? "";
  const esperada =
    "sha256=" + createHmac("sha256", secret).update(corpoBruto).digest("hex");
 
  const valida =
    recebida.length === esperada.length &&
    timingSafeEqual(Buffer.from(recebida), Buffer.from(esperada));
 
  if (!valida) return new Response("assinatura inválida", { status: 401 });
 
  const evento = JSON.parse(corpoBruto);
  // ... aqui você grava no seu banco
  return new Response("ok", { status: 200 });
}

Três detalhes que costumam quebrar a validação:

1. Use o corpo bruto. Se o seu framework já converteu para objeto e você reserializar, um único espaço diferente muda a assinatura.
2. Compare em tempo constante (timingSafeEqual), não com ===.
3. Responda 2xx só depois de aceitar o evento.

Caso de uso: gravar a conversa no seu SaaS

Assinando os dois eventos, o seu sistema recebe o diálogo completo — o que o cliente falou (conversation.inbound) e o que o agent respondeu (hermes.output) — e pode montar a timeline do atendimento na ficha da Ordem de Serviço.

Roteiro sugerido para o seu endpoint:

1. Validar a assinatura.
2. Ignorar o evento se o event_id já tiver sido processado (idempotência).
3. Localizar/criar o atendimento pelo conversation_id.
4. Gravar a mensagem com a data de created_at.
5. Responder 200.

Problemas comuns