Skip to main content

​
O que o comerciante implementa

Uma rota POST pública, por exemplo https://sua-api.com/webhooks/pix, que retorna 2xx rapidamente e aplica a lógica de negócio de forma assíncrona após validar a assinatura.

​
Registro

Use POST /webhook com URL e a lista de eventos — ver registro (TODO corpo).

​
Eventos suportados (strings exatas)

event na inscriçãoQuando dispara (origem)
pix_cash_inCash-in alcança terminal relevante (PAID / FAILED)
pix_cash_outCash-out confirmado ou falha terminal de liquidação
pix_cash_in_reversalRefund-in confirmado ou falha
pix_cash_out_reversalCash-out previamente confirmado é revertido

​
Formato do HTTP (saída)

POST https://sua-api.com/webhooks/pix
Content-Type: application/json
Digital-Signature: <base64 assinatura ECDSA P-256 SHA-256 do body>

​
Corpo (padrão)

O envelope inclui event_type e event com metadados (id, status, value_cents, end_to_end_id, taxas, timestamps). Exemplos completos: referência de eventos. TODO: tamanho máximo do corpo, compressão, charset — a origem não cita; validar com implementação (tipicamente UTF-8 JSON).

​
Resposta (SLA)

Responda 2xx em poucos segundos; a origem cita gama recomendada < 2–10 s. Falhas transitórias geram retentativas com backoff (fila). Seus handlers devem ser idempotentes.

​
Canais e latência (origem)

  • Cash-in / refund-in (outbox): entrega durável, commit + dispatcher (variáveis: PIX_STATUS_NOTIFICATION_*).
  • Cash-out e reversão: possível entrega com baixa latência via pool de goroutines, com fallback SQS em saturação/falha.
Não conte com ordem forte entre canais; deduplique e ordene com base em identificadores de negócio.

​
Segurança

​
Ver