Skip to main content

​
Assinatura HMAC-SHA256

Toda notificação de webhook é assinada com HMAC-SHA256, enviada no cabeçalho X-ParceleMais-Signature, para confirmar que a requisição veio da Parcele+ e não foi forjada por terceiros.
  • t — timestamp Unix (segundos) de quando a notificação foi enviada.
  • v1 — HMAC-SHA256 em hexadecimal, calculado sobre a string {t}.{corpo_bruto_da_requisição}, usando a chaveAssinatura do webhook.

SDK .NET

ParceleMaisWebhookEvent.Parse(rawJson, signatureHeader, signingSecret) já valida a assinatura e a janela de replay para você.
Se você não usa o SDK .NET, recalcule manualmente:
  1. Extraia t e v1 do cabeçalho X-ParceleMais-Signature.
  2. Calcule HMACSHA256("{t}.{corpo_bruto}", chaveAssinatura) em hexadecimal.
  3. Compare o resultado com v1 usando uma comparação de tempo constante (timingSafeEqual/CryptographicOperations.FixedTimeEquals — nunca == ou Equals).
  4. Rejeite se t estiver a mais de 5 minutos de distância do horário atual (proteção contra replay).
Sempre valide a assinatura contra o corpo bruto da requisição, antes de desserializar. Reformatar o JSON altera o hash calculado e invalida a comparação.

​
Autenticação do seu endpoint

Além da assinatura, você pode exigir uma credencial própria (Basic ou Bearer JWT) na configuração do webhook — veja os tipos de autenticação disponíveis.

​
Entregas não têm retentativa automática

Se o seu endpoint responder com erro ou timeout, a notificação não é reenviada automaticamente. Trate seu endpoint como não confiável por padrão: responda rápido (2xx) e processe de forma assíncrona, e use GET /v1/order/{id} para reconciliar o status caso desconfie de uma notificação perdida.

​
Deduplicação

O payload do webhook de Pedido não tem um identificador de evento próprio — apenas id_pedido e enum_status:
Use a combinação id_pedido + enum_status (+ o t do cabeçalho de assinatura, se quiser distinguir reenvios do mesmo status) como chave de deduplicação antes de processar.

​
Checklist de segurança

  • Valide a assinatura HMAC contra o corpo bruto, com comparação de tempo constante
  • Rejeite timestamps (t) fora da janela de replay
  • Configure autenticação (Basic ou JWT) na criação do webhook, além da assinatura
  • Responda 2xx rápido e processe de forma assíncrona
  • Deduplique por id_pedido + enum_status
  • Não assuma retentativa automática — reconcilie via GET /v1/order/{id} quando em dúvida