Todo webhook traz:
  • t: momento do envio (Unix, segundos).
  • v1: HMAC-SHA256(secret, "<t>.<corpo bruto>") em hexadecimal.
  • Durante a troca do secret vêm dois v1= (o do secret novo primeiro, depois o do antigo), por até 24 h. Aceite se qualquer um bater.

Como validar

  1. Leia o corpo bruto (bytes), antes de qualquer parse de JSON.
  2. Recalcule o HMAC com o seu whsec_....
  3. Compare em tempo constante.
  4. Rejeite se t estiver a mais de 5 minutos do seu relógio.
Assinatura inválida? Responda 400 e não processe. Nunca confie só no IP de origem.
A janela de 5 minutos mais a deduplicação pelo oripay-event-id impedem que alguém reaproveite um evento capturado.

O secret

  • Formato whsec_ + 32 bytes aleatórios em base64url. Mostrado uma vez, no OriPay Web, ao criar ou trocar. A API mostra só o prefixo (secret_prefix, os 10 primeiros caracteres).
  • A OriPay guarda o secret criptografado e nunca o envia em nenhum header ou resposta da API.
  • Trocar: OriPay Web → Conta → API → Webhook, com PIN. O antigo continua valendo por 24 h, e nesse período chegam dois v1=. Atualize o seu sistema e pronto.
  • Desconfia que vazou? Troque e marque revogar o antigo agora. A janela de 24 h é cancelada.
Use o evento de teste para conferir a validação logo depois de trocar.