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 hexadecimalOs passos
- 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.
- Separe t e v1Divida o cabeçalho por
,e cada parte no primeiro=. - 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.
- Calcule e compareHMAC-SHA256 de
t + "." + corpocom o segredo e compare comv1em tempo constante (timingSafeEqual,hmac.compare_digest), nunca com==. - 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.