Verificação de assinaturas
Como é assinado
O conteúdo assinado é o cabeçalho webhook-id, o cabeçalho webhook-timestamp e o corpo bruto da requisição unidos por pontos: <id>.<timestamp>.<body>. A chave é o seu segredo sem o prefixo whsec_, decodificado de base64. webhook-signature contém v1, seguido do HMAC-SHA256 em base64 desse conteúdo.
Enquanto um segredo rotacionado está no período de carência, webhook-signature traz duas assinaturas separadas por espaço, uma por segredo; aceite a entrega quando qualquer uma bater.
- Verifique o corpo bruto exatamente como recebido, antes de analisar o JSON: serializar de novo muda os bytes.
- Recuse um webhook-timestamp a mais de 5 minutos do seu relógio, para que uma requisição capturada não possa ser reproduzida depois.
- Compare as assinaturas em tempo constante.
- Responda 2xx rápido e faça o trabalho lento depois: esperamos 10 segundos.
Com uma biblioteca Standard Webhooks
Os pacotes standardwebhooks no npm e no PyPI (e bibliotecas para a maioria das outras linguagens) conferem a assinatura e o carimbo de data e hora em uma só chamada e lançam um erro quando um dos dois está errado.
// npm install standardwebhooksimport { Webhook } from "standardwebhooks";const wh = new Webhook(process.env.DOTWICK_WEBHOOK_SECRET); // whsec_…// Express: app.post("/dotwick", express.raw({ type: "application/json" }), handler)function handler(req, res) { let event; try { event = wh.verify(req.body.toString("utf8"), { "webhook-id": req.header("webhook-id"), "webhook-timestamp": req.header("webhook-timestamp"), "webhook-signature": req.header("webhook-signature"), }); } catch { return res.status(400).end(); } res.status(204).end(); // answer first, then work queue.add(event.type, event);}À mão
Sem dependência: a verificação inteira são poucas linhas da biblioteca padrão.
import { createHmac, timingSafeEqual } from "node:crypto";function verifyDotwick(secret, headers, rawBody) { const id = headers["webhook-id"]; const timestamp = headers["webhook-timestamp"]; const signatures = headers["webhook-signature"] ?? ""; if (!id || !timestamp) return false; if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false; const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64"); const expected = createHmac("sha256", key).update(`${id}.${timestamp}.${rawBody}`).digest(); return signatures.split(" ").some((entry) => { const [version, signature] = entry.split(","); const received = Buffer.from(signature ?? "", "base64"); return ( version === "v1" && received.length === expected.length && timingSafeEqual(received, expected) ); });}