Verificación de firma

Cada entrega de webhook incluye dos cabeceras usadas juntas:

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

La cadena hex después de sha256= es HMAC-SHA256(secret, timestamp + "." + raw_body). El punto es un byte literal; el timestamp es unix-segundos como ASCII.

Por qué verificar

Las URLs de webhook se filtran. Aparecen en logs de proxy, capturas de pantalla, historial del navegador, tickets de soporte de partners. Sin una comprobación de firma, cualquiera que aprenda tu URL puede POSTear un evento payment.settled falso y engañarte para cumplir órdenes no pagadas. La verificación prueba criptográficamente que la petición vino de InfraIO.

Incluir el timestamp dentro del payload firmado también te da protección contra replay: un atacante que capture una entrega no puede reenviarla más tarde sin que la firma se vuelva detectablemente obsoleta.

El algoritmo

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

Luego comprueba que el timestamp sea reciente (tolerancia típica: ±5 minutos).

Implementaciones

import { createHmac, timingSafeEqual } from "node:crypto";
 
const TOLERANCE_SECONDS = 5 * 60;
 
export function verifyInfraIo({
  body,
  signature,
  timestamp,
  secret,
}: {
  body: string;       // texto crudo — NO JSON parseado
  signature: string;  // valor de la cabecera X-Signature
  timestamp: string;  // valor de la cabecera X-Timestamp (unix seconds)
  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; // demasiado viejo o demasiado lejos en el 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 devuelve true si y solo si sig coincide con
// HMAC-SHA256(secret, timestamp + "." + body) Y el timestamp
// está dentro de la ventana de tolerancia.
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: bytes crudos. 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

Protección contra replay

El timestamp dentro del payload firmado es la primera línea de defensa: un atacante que capture una entrega no puede reenviarla tras la expiración de tu ventana de tolerancia.

Por si acaso (recomendado para eventos de alto valor como payment.settled):

1. Deduplica por X-Delivery en una tabla con restricción única. Los replays dentro de la ventana de tolerancia se vuelven no-ops: tu handler devuelve 200 sin hacer trabajo dos veces. Esta es la misma idempotencia que quieres para reintentos legítimos. (X-Delivery es estable a través de cada reintento de una entrega; el payload no lleva un campo event_id.)
2. Usa la tolerancia más pequeña que tu desviación de reloj permita. ±5 minutos es el default recomendado y coincide con lo que la mayoría de las flotas sincronizadas por NTP pueden sostener. Más estricto está bien; por debajo de ±30 segundos empezarás a rechazar entregas legítimas en redes con NTP aguas arriba lento.

Rotando un secreto

1. Dashboard → Developers → Webhooks → [endpoint] → ⋮ → Rotate Secret.
2. Se genera un nuevo secreto y se muestra exactamente una vez. Cópialo antes de cerrar el diálogo.
3. Actualiza tu variable de entorno y redespliega tu verificador dentro de 24 horas.

Ventana de gracia (doble firma)

Durante las 24 horas tras una rotación, cada entrega lleva dos firmas:

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

Un verificador corriendo el secreto anterior coincide con X-Signature-Prev; un verificador corriendo el secreto nuevo coincide con X-Signature. Que pase cualquiera de las cabeceras es suficiente: tu handler puede aceptar la entrega durante la migración sin retener el deploy.

Tras cerrar la ventana de gracia, solo se envía X-Signature. El secreto anterior deja de ser aceptado y cualquier verificador todavía configurado con él empezará a rechazar entregas: así que termina tu rollout dentro del presupuesto de 24 horas.

Patrón de receptor sugerido

// Acepta cualquier firma durante una ventana de gracia de rotación.
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));

Puedes eliminar la rama X-Signature-Prev tan pronto como la ventana de gracia en tu endpoint haya expirado y hayas quitado PREV_SECRET de tu env.

Revocación de emergencia

Si un secreto se filtró públicamente y necesitas invalidar el secreto anterior inmediatamente, es decir, no quieres que el solapamiento de 24 horas mantenga viva una clave conocidamente mala: rota dos veces. La primera rotación mueve el secreto filtrado al slot prev; la segunda rotación lo empuja fuera del slot prev (reemplazándolo con la clave aún-nueva) para que el valor filtrado ya no sea aceptado.

Probando tu cableado

En el dashboard, abre Developers → Webhooks y haz clic en Send Test en el endpoint que quieras verificar. Firmamos y POSTeamos un envelope sintético a la URL síncronamente, luego mostramos el status HTTP, latencia y un fragmento de 512 bytes de tu respuesta. Forma del 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..."
  }
}

El test ping usa el mismo esquema de firma que las entregas de producción, así que un check verde de este botón confirma que tu verificador acepta también eventos reales. Los test pings saltan el pipeline de reintentos de RMQ: si quieres ejercitar reintentos, dispara un evento real a través del flujo relevante de la API.

Fallos comunes