O que é webhook

Existem dois jeitos de descobrir que algo mudou em outro sistema. No polling, você pergunta de tempos em tempos: "já pagou?". No webhook, o outro sistema avisa quando acontece. O webhook gasta menos requisições e dispensa a espera entre uma consulta e outra.

Como funciona na API da xFlow

• Cadastro. Você registra uma URL em Integrações > Webhooks, no painel, ou por POST /api/v1/webhooks. A URL precisa ser https:// e pública. Cada conta pode ter até 20 endpoints.
• Entrega. A cada evento assinado, a xFlow envia um POST com corpo JSON no formato { event, data, createdAt }.
• Headers. x-webhook-event traz o nome do evento. x-webhook-signature traz sha256= seguido do HMAC-SHA256 do corpo cru, calculado com o segredo do endpoint.
• Confirmação. Responda com status 2xx. Sem isso, a entrega é reenviada até 3 vezes.
• Teste. Eventos gerados com chave de teste trazem livemode: false no data.

Os eventos disponíveis:

Exemplo

Validação da assinatura em Node.js, como na documentação:

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

// raw = corpo CRU da requisição (não faça JSON.parse antes de validar)
function isValid(raw, header, secret) {
  const expected = "sha256=" + createHmac("sha256", secret).update(raw).digest("hex");
  const a = Buffer.from(expected), b = Buffer.from(header ?? "");
  return a.length === b.length && timingSafeEqual(a, b);
}

O erro mais comum é validar o corpo depois de convertido em objeto. A assinatura vale para os bytes exatos que chegaram. A rota completa, com Express e com http nativo, está em API Pix em Node.js, e o guia de eventos em webhook Pix.

Cuidados

1. Valide a assinatura antes de qualquer outra coisa. Sem isso, qualquer um que descubra a URL pode simular um pagamento.
2. Seja idempotente. Como há reenvio, o mesmo evento pode chegar mais de uma vez. Dar baixa duas vezes no mesmo pedido não pode ter efeito.
3. Registre antes de confirmar. Grave o evento e só então responda 2xx. Se a gravação falhar, responda com erro para receber o reenvio.

Termos relacionados

• Idempotência: o que torna seguro receber o mesmo evento duas vezes.
• End-to-end ID: chega no data do transaction.paid.
• PSP: a instituição que confirma o pagamento antes do evento sair.