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 podem vazar por logs de proxy, screenshots, histórico de navegador e tickets de suporte. 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 que a requisição veio da InfraIO Pay.

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.

Para mais segurança (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 não são retentados. Para exercitar retries, dispare um evento real pelo fluxo de API relevante.

Falhas comuns