Verificação de assinatura

Toda entrega de webhook inclui dois headers usados em conjunto:

X-Signature: sha256=9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a8b
X-Timestamp: 1729536000

A string em hex depois de sha256= é HMAC-SHA256(secret, timestamp + "." + raw_body). O ponto é um byte literal; o timestamp é unix-segundos em ASCII.

Por que verificar

URLs de webhook vazam. Elas aparecem em logs de proxy, screenshots, histórico de navegador, tickets de suporte de parceiros. Sem uma checagem de assinatura, qualquer um que descobrir a sua URL pode fazer POST de um payment.settled falso e te enganar para entregar pedidos não pagos. A verificação prova criptograficamente que a requisição veio da InfraIO.

Incluir o timestamp dentro do payload assinado também te dá proteção contra replay: um atacante que captura uma entrega não consegue reenviá-la depois sem que a assinatura se torne detectavelmente velha.

O algoritmo

signed_payload  = timestamp + "." + raw_body
expected_header = "sha256=" + lowercase_hex( HMAC_SHA256(secret, signed_payload) )
constant_time_compare(expected_header, x_signature_header)

Depois confira que o timestamp está recente (tolerância típica: ±5 minutos).

Implementações

import { createHmac, timingSafeEqual } from "node:crypto";
 
const TOLERANCE_SECONDS = 5 * 60;
 
export function verifyInfraIo({
  body,
  signature,
  timestamp,
  secret,
}: {
  body: string;       // texto bruto — NÃO JSON parseado
  signature: string;  // valor do header X-Signature
  timestamp: string;  // valor do header X-Timestamp (unix segundos)
  secret: string;     // whsec_…
}): boolean {
  const ts = Number.parseInt(timestamp, 10);
  if (!Number.isFinite(ts)) return false;
  if (Math.abs(Math.floor(Date.now() / 1000) - ts) > TOLERANCE_SECONDS) {
    return false; // muito velho ou muito no futuro
  }
 
  const expected = "sha256=" + createHmac("sha256", secret)
    .update(`${timestamp}.${body}`)
    .digest("hex");
 
  const a = Buffer.from(signature);
  const b = Buffer.from(expected);
  return a.length === b.length && timingSafeEqual(a, b);
}

package infraio
 
import (
    "crypto/hmac"
    "crypto/sha256"
    "crypto/subtle"
    "encoding/hex"
    "strconv"
    "time"
)
 
const toleranceSeconds = 5 * 60
 
// VerifyWebhook returns true iff sig matches
// HMAC-SHA256(secret, timestamp + "." + body) AND the timestamp
// is within the tolerance window.
func VerifyWebhook(body []byte, sig, timestamp, secret string) bool {
    ts, err := strconv.ParseInt(timestamp, 10, 64)
    if err != nil {
        return false
    }
    skew := time.Now().Unix() - ts
    if skew < 0 {
        skew = -skew
    }
    if skew > toleranceSeconds {
        return false
    }
 
    mac := hmac.New(sha256.New, []byte(secret))
    mac.Write([]byte(timestamp))
    mac.Write([]byte("."))
    mac.Write(body)
    expected := "sha256=" + hex.EncodeToString(mac.Sum(nil))
    return subtle.ConstantTimeCompare([]byte(sig), []byte(expected)) == 1
}

import hmac, hashlib, time
 
TOLERANCE_SECONDS = 5 * 60
 
def verify_infraio(body: bytes, signature: str, timestamp: str, secret: str) -> bool:
    """body: raw bytes. signature: 'sha256=<hex>'. timestamp: unix seconds."""
    try:
        ts = int(timestamp)
    except ValueError:
        return False
    if abs(int(time.time()) - ts) > TOLERANCE_SECONDS:
        return False
 
    signed = timestamp.encode() + b"." + body
    expected = "sha256=" + hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(signature, expected)

require 'openssl'
 
TOLERANCE_SECONDS = 5 * 60
 
def verify_infraio(body, signature, timestamp, secret)
  ts = Integer(timestamp) rescue (return false)
  return false if (Time.now.to_i - ts).abs > TOLERANCE_SECONDS
 
  signed   = "#{timestamp}.#{body}"
  expected = "sha256=" + OpenSSL::HMAC.hexdigest("SHA256", secret, signed)
  Rack::Utils.secure_compare(signature.to_s, expected)
end

Proteção contra replay

O timestamp dentro do payload assinado é a primeira linha de defesa — um atacante que captura uma entrega não consegue reenviar depois que a sua janela de tolerância expira.

Cinto e suspensório (recomendado para eventos de alto valor como payment.settled):

1. Deduplique em X-Delivery numa tabela com uma constraint de unicidade. Replays dentro da janela de tolerância viram no-ops — o seu handler retorna 200 sem fazer o trabalho duas vezes. É a mesma idempotência que você quer para retentativas legítimas. (X-Delivery é estável em todas as retentativas de uma entrega; o payload não traz um campo event_id.)
2. Use a menor tolerância que a sua defasagem de relógio permite. ±5 minutos é o padrão recomendado e bate com o que a maioria das frotas sincronizadas via NTP consegue sustentar. Mais apertado tudo bem; abaixo de ±30 segundos você vai começar a rejeitar entregas legítimas em redes com NTP upstream lento.

Rotacionando um segredo

1. Dashboard → Developers → Webhooks → [endpoint] → ⋮ → Rotate Secret.
2. Um segredo novo é gerado e mostrado exatamente uma vez. Copie antes de fechar a caixa de diálogo.
3. Atualize a sua env var e redeploye o seu verificador dentro de 24 horas.

Janela de tolerância (assinatura dupla)

Pelas 24 horas depois de uma rotação, toda entrega leva duas assinaturas:

X-Signature:       sha256=<hmac(new_secret,  ts + "." + body)>
X-Signature-Prev:  sha256=<hmac(prev_secret, ts + "." + body)>
X-Timestamp:       1729536000

Um verificador rodando o segredo anterior combina com X-Signature-Prev; um verificador rodando o segredo novo combina com X-Signature. Qualquer um dos headers passando já é suficiente — o seu handler pode aceitar a entrega durante a migração sem segurar o deploy.

Depois que a janela de tolerância fecha, só X-Signature é enviado. O segredo anterior para de ser aceito e qualquer verificador ainda configurado com ele vai começar a rejeitar entregas — então termine o seu rollout dentro do orçamento de 24 horas.

Padrão sugerido de receptor

// Aceita qualquer das duas assinaturas durante uma janela de tolerância de rotação.
const sig     = req.headers["x-signature"]      ?? "";
const sigPrev = req.headers["x-signature-prev"] ?? "";
const ok = verify(body, sig, ts, CURRENT_SECRET)
       || (PREV_SECRET && verify(body, sigPrev, ts, PREV_SECRET));

Você pode descartar o ramo X-Signature-Prev assim que a janela de tolerância no seu endpoint tiver expirado e você tiver removido o PREV_SECRET do seu env.

Revogação emergencial

Se um segredo vazou publicamente e você precisa invalidar o segredo anterior imediatamente — ou seja, você não quer que a sobreposição de 24 horas mantenha uma chave conhecidamente comprometida viva — rotacione duas vezes. A primeira rotação move o segredo vazado para o slot anterior; a segunda rotação empurra para fora do slot anterior (substituindo pela chave ainda-nova) para que o valor vazado não seja mais aceito.

Testando o seu wiring

No dashboard, abra Developers → Webhooks e clique em Send Test no endpoint que você quer verificar. A gente assina e faz POST de um envelope sintético para a URL de forma síncrona, e depois mostra o status HTTP, latência e um snippet de 512 bytes da sua resposta. Formato do payload:

{
  "event_id":   "<uuid>",
  "event_type": "webhook.test.ping",
  "created_at": "2026-05-17T12:00:00Z",
  "test":       true,
  "data": {
    "merchant_id": "<your-merchant-id>",
    "webhook_id":  "<endpoint-id>",
    "message":     "Test ping from the merchant dashboard..."
  }
}

O test ping usa o mesmo esquema de assinatura que entregas de produção, então um check verde nesse botão confirma que o seu verificador aceita eventos reais também. Test pings contornam a pipeline RMQ de retry — se você quer exercitar retries, dispare um evento real pelo fluxo de API relevante.

Falhas comuns