Webhooks e eventos que o Pipe envia

Passo a passo: cadastrar

1. Na Gestão, abra o fluxo e vá em Integrações.
2. No cartão Webhook, conecte e informe o Endereço HTTPS.
3. Marque os eventos que quer receber. Por padrão, todos vêm marcados.
4. Se o seu endereço exige autenticação, escolha o tipo: básica (usuário e senha) ou OAuth2 com credenciais do cliente. Você também pode acrescentar cabeçalhos próprios.
5. Salve e copie o segredo exibido. Ele serve para validar as assinaturas e aparece uma vez.

Eventos

Um webhook de um fluxo recebe só os eventos desse fluxo (e, num roteador, dos serviços dele).

Formato do envio

Cada evento chega como POST com Content-Type: application/json:

{
  "event": "conversa.criada",
  "delivery_id": "6f1d2a52-0000-4000-8000-0000000000bb",
  "tenant_id": "b3a1c9de-0000-4000-8000-0000000000aa",
  "occurred_at": "2026-10-12T14:30:00.000Z",
  "data": { "conversa_id": "b3a1c9de-0000-4000-8000-000000000100" }
}

O conteúdo de data varia por evento. Use delivery_id do corpo para ignorar um evento repetido.

Cabeçalhos enviados:

Validar a assinatura

O HMAC é calculado com o seu segredo sobre o texto "<timestamp>.<corpo>", com o corpo exatamente como foi recebido. Exemplo em Node.js:

import { createHmac, timingSafeEqual } from 'node:crypto';

function assinaturaValida(segredo, timestamp, corpoCru, assinaturaRecebida) {
  const esperada = 'sha256=' + createHmac('sha256', segredo)
    .update(`${timestamp}.${corpoCru}`)
    .digest('hex');
  const a = Buffer.from(esperada);
  const b = Buffer.from(assinaturaRecebida);
  return a.length === b.length && timingSafeEqual(a, b);
}

Recuse também envios com X-Pipe-Timestamp muito antigo. A tolerância recomendada é de 300 segundos (5 minutos), o que impede o reaproveitamento de um envio capturado.

Tentativas e entregas

• O Pipe espera até 5 segundos pela resposta. Qualquer 2xx conta como entregue.
• Se falhar, tenta de novo com espera crescente (10 segundos, depois 20, 40 e assim por diante, até 1 hora entre tentativas), até 5 tentativas por padrão.
• Esgotadas as tentativas, a entrega vira descartada.

Estados de uma entrega: pendente, entregue, falhou e descartada.

Consultar webhooks e entregas por API

curl -s "https://http.pipebr.app/v1/webhooks/b3a1c9de-0000-4000-8000-000000000900/deliveries?state=descartada" \
  -H "Authorization: Bearer $PIPE_CHAVE"

{
  "data": [
    {
      "id": "b3a1c9de-0000-4000-8000-000000000a00",
      "event": "conversa.criada",
      "state": "descartada",
      "attempts": 5,
      "lastError": "HTTP 500",
      "nextAttemptAt": null,
      "createdAt": "2026-10-12T14:30:00.000Z"
    }
  ],
  "page_info": { "has_next_page": false, "end_cursor": null }
}

Por segurança, a API nunca devolve o segredo, as credenciais, os valores dos cabeçalhos, os parâmetros da URL nem o conteúdo dos eventos. A URL volta mascarada, como https://exemplo.test/hook/….