Webhooks — Segurança e verificação - SuperSign

Como confirmar que uma entrega veio mesmo da SuperSign e não foi alterada, e como trocar o segredo. Visão geral em Webhooks.

Verificação da assinatura (HMAC)

Quando o endpoint tem um segredo de assinatura habilitado, toda entrega leva o header:

X-SuperSign-Signature: t=1700000000,v1=<hex>

t é o horário do disparo em segundos (epoch).

v1 é HMAC-SHA256(segredo, "<t>.<corpo cru>") em hexadecimal.

A assinatura é calculada sobre o corpo exato recebido (os bytes do POST), não sobre um objeto reserializado — verifique sobre o raw body, antes de qualquer parse.

Passo a passo: (1) leia t e v1 do header; (2) rejeite se |agora − t| for maior que a sua tolerância (ex.: 5 min) — isso barra replay; (3) calcule o HMAC de "<t>.<raw body>" com o seu segredo e compare com v1 em tempo constante.

O segredo (whsec_...) aparece uma vez ao gerar/rotacionar na tela do Desenvolvedor, e pode ser revelado por quem administra a integração. Todo endpoint cadastrado hoje já nasce com segredo, devolvido uma única vez na resposta do cadastro. Um endpoint antigo, cadastrado antes de existir o segredo, chega sem o header; para passar a assinar, gire o segredo dele (veja Girar o segredo de assinatura).

Ainda assim, para ação irreversível (liberar dinheiro, acesso, documento), confirme o envelope pela rota autenticada como reforço:

Valide também event, formato dos IDs e estado esperado. Não exija environment — ele só existe na Sandbox. Nunca confie apenas em campos de contato recebidos no payload.

Girar o segredo de assinatura

{ "data": { "secret": "whsec_..." } }

Esta operação não é idempotente — ela não aceita nem guarda
Idempotency-Key. Cada chamada gera um segredo novo e invalida o
anterior na hora; chamar de novo não devolve o segredo antigo, nunca. Se você
não tiver certeza se a chamada anterior chegou a girar o segredo, chame de
novo: o resultado é sempre um segredo válido e atual. O segredo em texto puro
só aparece nesta resposta — guarde-o agora. A
rotação substitui o segredo na hora: não há período de convivência entre
o antigo e o novo. Da resposta em diante, toda tentativa de disparo — inclusive
as retentativas de entregas que já estavam em curso — sai assinada com o
segredo novo. Como o novo só existe depois da chamada, haverá uma janela entre
a rotação e a atualização do seu verificador em que as assinaturas não
conferem: as entregas continuam chegando normalmente, só a verificação falha.
Para não perder eventos nessa janela, faça seu endpoint responder 5xx quando
a assinatura não conferir (a entrega será retentada) ou reenvie depois as
entregas FAILED com a operação de reenvio (veja Entregas, retentativas e reenvio).

Não existe uma operação para revelar um segredo já existente na API
pública (ela existe na tela do Desenvolvedor, para quem administra a conta
pelo navegador). Perdeu o segredo? Rotacione: você recebe um novo na hora.

Privacidade e operação

O payload pode conter nome, e-mail e telefone de signatários; proteja logs e filas.

Não registre sua API Key nem URLs temporárias de download.

Monitore falhas e latência do endpoint.

Responda 2xx a eventos desconhecidos depois de registrá-los: novos tipos de evento podem ser adicionados, e responder 5xx, 404 ou outro status retentável (veja Entregas, retentativas e reenvio) a um evento que você ainda não conhece faz a entrega ser retentada por até ~7 horas.

Mantenha o consumidor tolerante a novos campos.

Webhooks — Segurança e verificação

Verificação da assinatura (HMAC)#

Girar o segredo de assinatura#

Privacidade e operação#

Verificação da assinatura (HMAC)

Girar o segredo de assinatura

Privacidade e operação