Verificar X-Signature

Toda entrega vem assinada com o segredo do endpoint. Conferir a assinatura é o que garante que o evento veio da plataforma e não foi alterado nem reaproveitado.

O cabeçalho

X-Signature: t=<unix>,v1=<hex>. t é a hora do envio em segundos; v1 é o HMAC-SHA256, em hexadecimal, de "<t>.<corpo cru>", com o segredo whsec_… inteiro (com o prefixo) como chave. Cada tentativa é assinada de novo, com o t dela.

O que é assinado
X-Signature: t=1793716329,v1=<hex>

conteúdo assinado = "1793716329" + "." + <corpo cru>
v1               = HMAC-SHA256(segredo "whsec_…", conteúdo assinado), em hexadecimal

Os passos

  1. Leia o corpo cruOs bytes exatos que chegaram, antes de qualquer parse. JSON lido e montado de novo muda espaços e ordem, e a conta não fecha.
  2. Separe t e v1Divida o cabeçalho por , e cada parte no primeiro =.
  3. Recuse carimbo velhoMais de 300 segundos de diferença do seu relógio, para mais ou para menos: recuse. Isso impede reenviar uma entrega antiga capturada.
  4. Calcule e compareHMAC-SHA256 de t + "." + corpo com o segredo e compare com v1 em tempo constante (timingSafeEqual, hmac.compare_digest), nunca com ==.
  5. Só então trate o eventoAssinatura inválida: responda 400 e não faça nada. A entrega volta a ser tentada, o que ajuda se o erro foi seu (por exemplo, segredo antigo).

Erros comuns

  • Usar o body já transformado pelo framework. No Express, receba com express.raw({ type: "application/json" }); no Flask, request.get_data().
  • Usar o segredo sem o prefixo whsec_: a chave do HMAC é o segredo inteiro.
  • Segredo do outro ambiente: teste e produção têm endpoints e segredos separados.
  • Relógio do servidor fora da hora: sincronize com NTP, senão a tolerância de 300 s recusa entregas boas.
  • Esquecer de atualizar depois de trocar o segredo no painel: a troca vale na hora (veja Trocar o segredo).

A assinatura prova a origem; o status de agora vem do evento mais recente. Na dúvida, consulte o recurso pela API antes de agir.