Webhooks — conceitos e segurança

Webhooks são notificações HTTP POST enviadas pela BS Finance para uma URL sua sempre que um evento relevante acontece (Pix recebido, devolução concluída, infração aberta, cobrança paga, etc).

Garantias de entrega

• Entrega at-least-once: o mesmo evento pode chegar mais de uma vez. Implemente idempotência usando o campo event_id.
• Retentativas exponenciais por até 24 horas em caso de falha (timeout, 5xx, conexão recusada).
• Timeout de 10 segundos por requisição. Responda rapidamente com 2xx e processe o payload em background.

Verificação de assinatura

Cada requisição inclui o header BS-Signature contendo um HMAC SHA-256 do corpo usando o secret configurado no webhook.

import crypto from "node:crypto";

function verify(signature, rawBody, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}