Referência de Webhooks

Receba confirmações de liquidação Pix e alertas do MED 2.0 com garantia de entrega.

1. Política de Retentativas (Exponential Backoff)

Assim que o Banco Central confirma a liquidação de um Pix, nossos workers assíncronos (Celery) disparam uma requisição POST para a webhook_url configurada pela sua empresa. Caso o seu servidor não retorne um código HTTP 2xx em até 10 segundos, reenviamos o evento automaticamente em intervalos progressivos.

2. Evento de Liquidação Confirmada (pix.paid)

Utilize o campo txid para dar baixa automática no pedido ou fatura dentro do seu ERP:

Payload POST — Evento pix.paid

json

{
  "event": "pix.paid",
  "txid": "PXSP891234ABCDEF56789012345678",
  "e2e_id": "E18236120202610311500s0123456789",
  "status": "PAID",
  "amount": 250.00,
  "paid_at": "2026-10-31T15:00:04Z"
}

3. Evento de Infração Bacen (med.dispute.opened)

Disparado quando uma transação entra em análise pelo Mecanismo Especial de Devolução (MED), permitindo que o seu sistema bloqueie a entrega do pedido ou envie evidências de defesa:

Payload POST — Evento med.dispute.opened

json

{
  "event": "med.dispute.opened",
  "dispute_id": "c41b9201-7e42-488a-912c-8472910a11b2",
  "txid": "PXSP891234ABCDEF56789012345678",
  "amount": 250.00,
  "reason": "Suspeita de fraude reportada pela instituição pagadora",
  "status": "OPEN"
}

4. Validando a Assinatura Digital (X-PixSplit-Signature)

Para garantir que o POST veio genuinamente da PixSplit, valide o cabeçalho X-PixSplit-Signature gerando o hash HMAC-SHA256 do corpo da requisição:

Validação de Segurança HMAC-SHA256 (Node.js / TypeScript)

typescript

import crypto from "crypto";

export function verifyPixSplitWebhook(rawBody: string, signatureHeader: string, secret: string) {
  const expectedSignature = crypto
    .createHmac("sha256", secret)
    .update(rawBody, "utf8")
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(signatureHeader),
    Buffer.from(expectedSignature)
  );
}