Ctrl K⌘K
Actualizado: Markdown Abrir en Claude Abrir en ChatGPT
En esta página

Verificación de firma

Comprueba que cada webhook te lo enviamos nosotros y que nadie lo alteró, con un HMAC-SHA256 del cuerpo crudo calculado con tu secreto.

Tu endpoint de webhooks es una URL pública, así que cualquiera puede enviarle una petición. Antes de procesar un evento, tu servidor debe comprobar su firma: es la única forma de saber que te lo enviamos nosotros y que el cuerpo llegó tal como salió.

Esta página explica cómo se forma la cabecera de firma, el algoritmo para verificarla paso a paso y ejemplos listos en cada lenguaje, con un vector de prueba para confirmar que tu código calcula bien. También explica las cabeceras del estándar abierto Standard Webhooks, que traen la misma entrega firmada para que puedas verificarla con una librería, cuánta diferencia de tiempo aceptar, cómo rotar el secreto sin perder entregas y qué revisar cuando la verificación falla.

Importante

Ambiente de pruebas: sin validez fiscal. El algoritmo es el mismo en pruebas y en producción, y cada destino tiene su propio secreto.

Conceptos#

Calculamos un HMAC-SHA256 sobre el cuerpo que te enviamos y lo ponemos en la cabecera Ecuafact-Signature. Un HMAC es un código que solo puede generar quien conoce el secreto, así que tu servidor repite el cálculo con el mismo secreto y, si los dos valores coinciden, sabe que el evento es auténtico y que nadie modificó el cuerpo en el camino.

La firma incluye además una marca de tiempo. Gracias a ella, nadie puede capturar un evento válido y reenviártelo días después, lo que se conoce como un ataque de repetición.

Cada entrega trae la firma en dos formatos, calculados con el mismo secreto: Ecuafact-Signature, nuestra cabecera de siempre, y las cabeceras de Standard Webhooks. Basta con que verifiques una.

Prerequisitos#

  • El secreto del destino, guardado en ECUAFACT_WEBHOOK_SECRET. El portal lo muestra una sola vez, al crear el destino o al rotarlo en Integración > Eventos, como se explica en Webhooks.
  • Acceso al cuerpo crudo de la petición en tu framework, es decir, a los bytes tal como llegaron, antes de deserializarlos.
  • El reloj de tu servidor sincronizado por NTP, para validar la marca de tiempo.

La cabecera Ecuafact-Signature#

Cada entrega trae una cabecera como esta:

Ecuafact-Signature: t=1791385446,v1=3e2365076d2a218f96f8845e726567b874ad07c63304e217977cfc6368605d20
Parte Formato Descripción
t Entero, segundos Unix (UTC) Momento en que se firmó esta entrega. Cambia en cada reintento.
v1 64 caracteres hexadecimales en minúsculas HMAC-SHA256 de la cadena firmada, con tu secreto como clave.

Las partes van separadas por coma y cada una tiene la forma nombre=valor. Lee cada parte por su nombre y no por su posición, e ignora cualquier parte distinta de t y v1.

El secreto es un texto de 44 caracteres, por ejemplo c2VjcmV0by1kZS1wcnVlYmFzLW5vLXVzYXItMzJieXQ=. Aunque parece Base64, úsalo tal cual, porque la clave del HMAC son los bytes UTF-8 de ese texto y no el resultado de decodificarlo.

Cadena firmada#

El valor v1 es el HMAC-SHA256 de esta cadena:

<t> + "." + <cuerpo crudo>
  • <t> es el valor de t de la cabecera, como texto; por ejemplo, 1791385446.
  • <cuerpo crudo> es el cuerpo de la petición exactamente como llegó, sin reindentar, reordenar claves ni quitar espacios. El cuerpo llega en UTF-8.

Algoritmo paso a paso#

Tu servidor verifica cada entrega con estos pasos, en este orden:

  1. Lee la cabecera Ecuafact-Signature. Si falta, rechaza la entrega con un 401.
  2. Separa la cabecera por comas, quita los espacios de cada parte y obtén t y v1. Si falta alguno o t no es un entero, rechaza la entrega.
  3. Compara t con tu reloj. Si la diferencia es mayor que tu tolerancia, que te recomendamos fijar en 300 segundos, rechaza la entrega.
  4. Construye la cadena t + "." + cuerpo_crudo.
  5. Calcula HMAC-SHA256 de esa cadena (bytes UTF-8) con el secreto (bytes UTF-8) como clave.
  6. Convierte el resultado a hexadecimal en minúsculas.
  7. Compara tu resultado con v1, pasado a minúsculas, usando una comparación de tiempo constante. Si no coinciden, rechaza la entrega.
  8. Solo ahora interpreta el JSON y procesa el evento.

Atención

Calcula el HMAC sobre el cuerpo crudo. Si tu framework deserializa el JSON y lo vuelves a serializar, la firma no coincide aunque el contenido sea el mismo. Y nunca proceses un evento cuya firma no verificaste, porque cualquiera puede llamar a tu URL.

Verificación#

Cada ejemplo define la función de verificación y la prueba con el vector de prueba. Si tu código está bien, imprime true (o True en Python). La función recibe el instante actual como parámetro para que puedas probarla con un vector de fecha fija; en tu endpoint, pásale la hora actual. Las pestañas SDK usan el verificador incluido en cada SDK oficial, y la pestaña CLI verifica la misma firma con ecuafact webhooks verificar, que lee el secreto de ECUAFACT_WEBHOOK_SECRET.

# Herramienta de diagnostico: no compara en tiempo constante. No la uses en produccion.
SECRETO='c2VjcmV0by1kZS1wcnVlYmFzLW5vLXVzYXItMzJieXQ='
CABECERA='t=1791385446,v1=3e2365076d2a218f96f8845e726567b874ad07c63304e217977cfc6368605d20'
CUERPO='{"idOperacion":"3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f","estado":"autorizado","codEstado":2001,"errores":[],"tipoDocumento":"01","claveAcceso":"0710202601012345678900110010010000001231234567811","eventType":"document.authorized","resourceId":"3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f","occurredAtUtc":"2026-10-07T15:04:05.1234567Z"}'

T=$(printf '%s' "$CABECERA" | sed -n 's/.*t=\([0-9]*\).*/\1/p')
V1=$(printf '%s' "$CABECERA" | sed -n 's/.*v1=\([0-9a-fA-F]*\).*/\1/p' | tr 'A-F' 'a-f')
ESPERADO=$(printf '%s' "$T.$CUERPO" | openssl dgst -sha256 -hmac "$SECRETO" | sed 's/^.*= //')
[ "$ESPERADO" = "$V1" ] && echo "true" || echo "false"
using System.Security.Cryptography;
using System.Text;

const string Secreto = "c2VjcmV0by1kZS1wcnVlYmFzLW5vLXVzYXItMzJieXQ=";
const string Cabecera = "t=1791385446,v1=3e2365076d2a218f96f8845e726567b874ad07c63304e217977cfc6368605d20";
const string Cuerpo = """{"idOperacion":"3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f","estado":"autorizado","codEstado":2001,"errores":[],"tipoDocumento":"01","claveAcceso":"0710202601012345678900110010010000001231234567811","eventType":"document.authorized","resourceId":"3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f","occurredAtUtc":"2026-10-07T15:04:05.1234567Z"}""";

// En tu endpoint: ahora = DateTimeOffset.UtcNow.ToUnixTimeSeconds()
Console.WriteLine(Verificar(Secreto, Cabecera, Cuerpo, ahora: 1791385446, toleranciaSegundos: 300));

static bool Verificar(string secreto, string cabecera, string cuerpoCrudo, long ahora, long toleranciaSegundos)
{
    string? t = null;
    string? v1 = null;
    foreach (string parte in cabecera.Split(','))
    {
        string item = parte.Trim();
        if (item.StartsWith("t=", StringComparison.Ordinal))
        {
            t = item.Substring(2);
        }
        else if (item.StartsWith("v1=", StringComparison.Ordinal))
        {
            v1 = item.Substring(3);
        }
    }
    if (t == null || v1 == null || !long.TryParse(t, out long unix))
    {
        return false;
    }
    if (Math.Abs(ahora - unix) > toleranciaSegundos)
    {
        return false;
    }
    using HMACSHA256 hmac = new(Encoding.UTF8.GetBytes(secreto));
    byte[] hash = hmac.ComputeHash(Encoding.UTF8.GetBytes(t + "." + cuerpoCrudo));
    string esperado = Convert.ToHexString(hash).ToLowerInvariant(); // ToHexString devuelve MAYUSCULAS
    return CryptographicOperations.FixedTimeEquals(
        Encoding.ASCII.GetBytes(esperado),
        Encoding.ASCII.GetBytes(v1.ToLowerInvariant()));
}
import hashlib
import hmac
import time

SECRETO = "c2VjcmV0by1kZS1wcnVlYmFzLW5vLXVzYXItMzJieXQ="
CABECERA = "t=1791385446,v1=3e2365076d2a218f96f8845e726567b874ad07c63304e217977cfc6368605d20"
CUERPO = ('{"idOperacion":"3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f","estado":"autorizado","codEstado":2001,"errores":[],"tipoDocumento":"01",'
          '"claveAcceso":"0710202601012345678900110010010000001231234567811",'
          '"eventType":"document.authorized","resourceId":"3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f",'
          '"occurredAtUtc":"2026-10-07T15:04:05.1234567Z"}')


def verificar(secreto, cabecera, cuerpo_crudo, ahora=None, tolerancia=300):
    partes = dict(p.strip().split("=", 1) for p in cabecera.split(",") if "=" in p)
    t, v1 = partes.get("t"), partes.get("v1")
    if not t or not v1 or not t.isdigit():
        return False
    ahora = int(time.time()) if ahora is None else ahora
    if abs(ahora - int(t)) > tolerancia:
        return False
    firmado = f"{t}.{cuerpo_crudo}".encode("utf-8")
    esperado = hmac.new(secreto.encode("utf-8"), firmado, hashlib.sha256).hexdigest()
    return hmac.compare_digest(esperado, v1.lower())


# En tu endpoint omite "ahora" para usar la hora actual.
print(verificar(SECRETO, CABECERA, CUERPO, ahora=1791385446))
// Node.js 18 o superior. Guarda como firma.mjs y ejecuta: node firma.mjs
import { createHmac, timingSafeEqual } from 'node:crypto';

const SECRETO = 'c2VjcmV0by1kZS1wcnVlYmFzLW5vLXVzYXItMzJieXQ=';
const CABECERA = 't=1791385446,v1=3e2365076d2a218f96f8845e726567b874ad07c63304e217977cfc6368605d20';
const CUERPO = '{"idOperacion":"3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f","estado":"autorizado","codEstado":2001,"errores":[],"tipoDocumento":"01","claveAcceso":"0710202601012345678900110010010000001231234567811","eventType":"document.authorized","resourceId":"3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f","occurredAtUtc":"2026-10-07T15:04:05.1234567Z"}';

function verificar(secreto, cabecera, cuerpoCrudo, ahora = Math.floor(Date.now() / 1000), tolerancia = 300) {
  let t = null;
  let v1 = null;
  for (const parte of cabecera.split(',')) {
    const item = parte.trim();
    if (item.startsWith('t=')) t = item.slice(2);
    else if (item.startsWith('v1=')) v1 = item.slice(3).toLowerCase();
  }
  if (!t || !v1 || !/^\d+$/.test(t)) return false;
  if (Math.abs(ahora - Number(t)) > tolerancia) return false;
  const esperado = createHmac('sha256', secreto).update(`${t}.${cuerpoCrudo}`, 'utf8').digest('hex');
  const a = Buffer.from(esperado, 'utf8');
  const b = Buffer.from(v1, 'utf8');
  return a.length === b.length && timingSafeEqual(a, b);
}

// En tu endpoint omite "ahora" para usar la hora actual.
console.log(verificar(SECRETO, CABECERA, CUERPO, 1791385446));
<?php
$secreto = 'c2VjcmV0by1kZS1wcnVlYmFzLW5vLXVzYXItMzJieXQ=';
$cabecera = 't=1791385446,v1=3e2365076d2a218f96f8845e726567b874ad07c63304e217977cfc6368605d20';
$cuerpo = '{"idOperacion":"3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f","estado":"autorizado","codEstado":2001,"errores":[],"tipoDocumento":"01","claveAcceso":"0710202601012345678900110010010000001231234567811","eventType":"document.authorized","resourceId":"3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f","occurredAtUtc":"2026-10-07T15:04:05.1234567Z"}';

function verificar(string $secreto, string $cabecera, string $cuerpoCrudo, ?int $ahora = null, int $tolerancia = 300): bool
{
    $partes = [];
    foreach (explode(',', $cabecera) as $p) {
        $kv = explode('=', trim($p), 2);
        if (count($kv) === 2) {
            $partes[$kv[0]] = $kv[1];
        }
    }
    $t = $partes['t'] ?? null;
    $v1 = $partes['v1'] ?? null;
    if ($t === null || $v1 === null || !ctype_digit($t)) {
        return false;
    }
    if (abs(($ahora ?? time()) - (int) $t) > $tolerancia) {
        return false;
    }
    $esperado = hash_hmac('sha256', $t . '.' . $cuerpoCrudo, $secreto);
    return hash_equals($esperado, strtolower($v1));
}

// En tu endpoint omite $ahora para usar la hora actual.
var_dump(verificar($secreto, $cabecera, $cuerpo, 1791385446));
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.util.HashMap;
import java.util.Map;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

public class Firma {

    public static void main(String[] args) throws Exception {
        String secreto = "c2VjcmV0by1kZS1wcnVlYmFzLW5vLXVzYXItMzJieXQ=";
        String cabecera = "t=1791385446,v1=3e2365076d2a218f96f8845e726567b874ad07c63304e217977cfc6368605d20";
        String cuerpo = """
            {"idOperacion":"3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f","estado":"autorizado","codEstado":2001,"errores":[],"tipoDocumento":"01","claveAcceso":"0710202601012345678900110010010000001231234567811","eventType":"document.authorized","resourceId":"3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f","occurredAtUtc":"2026-10-07T15:04:05.1234567Z"}""";
        // En tu endpoint: ahora = java.time.Instant.now().getEpochSecond()
        System.out.println(verificar(secreto, cabecera, cuerpo, 1791385446L, 300));
    }

    static boolean verificar(String secreto, String cabecera, String cuerpoCrudo, long ahora, long tolerancia) throws Exception {
        Map<String, String> partes = new HashMap<>();
        for (String p : cabecera.split(",")) {
            String[] kv = p.trim().split("=", 2);
            if (kv.length == 2) {
                partes.put(kv[0], kv[1]);
            }
        }
        String t = partes.get("t");
        String v1 = partes.get("v1");
        if (t == null || v1 == null || !t.matches("\\d+")) {
            return false;
        }
        if (Math.abs(ahora - Long.parseLong(t)) > tolerancia) {
            return false;
        }
        Mac mac = Mac.getInstance("HmacSHA256");
        mac.init(new SecretKeySpec(secreto.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
        byte[] hash = mac.doFinal((t + "." + cuerpoCrudo).getBytes(StandardCharsets.UTF_8));
        StringBuilder hex = new StringBuilder();
        for (byte b : hash) {
            hex.append(String.format("%02x", b));
        }
        return MessageDigest.isEqual(
            hex.toString().getBytes(StandardCharsets.US_ASCII),
            v1.toLowerCase().getBytes(StandardCharsets.US_ASCII));
    }
}
using Ecuafact.Sdk.Webhooks;

const string Secreto = "c2VjcmV0by1kZS1wcnVlYmFzLW5vLXVzYXItMzJieXQ=";
const string Cabecera = "t=1791385446,v1=3e2365076d2a218f96f8845e726567b874ad07c63304e217977cfc6368605d20";
const string Cuerpo = """{"idOperacion":"3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f","estado":"autorizado","codEstado":2001,"errores":[],"tipoDocumento":"01","claveAcceso":"0710202601012345678900110010010000001231234567811","eventType":"document.authorized","resourceId":"3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f","occurredAtUtc":"2026-10-07T15:04:05.1234567Z"}""";

// En tu endpoint usa DateTimeOffset.UtcNow en lugar del instante fijo del vector.
bool valido = WebhookSignature.Verify(Secreto, Cabecera, Cuerpo,
    DateTimeOffset.FromUnixTimeSeconds(1791385446), TimeSpan.FromMinutes(5));
Console.WriteLine(valido);
from ecuafact import verify

SECRETO = "c2VjcmV0by1kZS1wcnVlYmFzLW5vLXVzYXItMzJieXQ="
CABECERA = "t=1791385446,v1=3e2365076d2a218f96f8845e726567b874ad07c63304e217977cfc6368605d20"
CUERPO = ('{"idOperacion":"3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f","estado":"autorizado","codEstado":2001,"errores":[],"tipoDocumento":"01",'
          '"claveAcceso":"0710202601012345678900110010010000001231234567811",'
          '"eventType":"document.authorized","resourceId":"3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f",'
          '"occurredAtUtc":"2026-10-07T15:04:05.1234567Z"}')

# En tu endpoint omite "now" para usar la hora actual.
print(verify(SECRETO, CABECERA, CUERPO, now=1791385446, tolerance_seconds=300))
// Node.js 18 o superior. Guarda como firma.mjs y ejecuta: node firma.mjs
import { verify } from "@ecuafact/sdk";

const SECRETO = "c2VjcmV0by1kZS1wcnVlYmFzLW5vLXVzYXItMzJieXQ=";
const CABECERA = "t=1791385446,v1=3e2365076d2a218f96f8845e726567b874ad07c63304e217977cfc6368605d20";
const CUERPO = '{"idOperacion":"3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f","estado":"autorizado","codEstado":2001,"errores":[],"tipoDocumento":"01","claveAcceso":"0710202601012345678900110010010000001231234567811","eventType":"document.authorized","resourceId":"3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f","occurredAtUtc":"2026-10-07T15:04:05.1234567Z"}';

// En tu endpoint usa new Date() en lugar del instante fijo del vector.
console.log(verify(SECRETO, CABECERA, CUERPO, new Date(1791385446 * 1000), 300));
<?php
require 'vendor/autoload.php';

use Ecuafact\Sdk\WebhookSignature;

$secreto = 'c2VjcmV0by1kZS1wcnVlYmFzLW5vLXVzYXItMzJieXQ=';
$cabecera = 't=1791385446,v1=3e2365076d2a218f96f8845e726567b874ad07c63304e217977cfc6368605d20';
$cuerpo = '{"idOperacion":"3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f","estado":"autorizado","codEstado":2001,"errores":[],"tipoDocumento":"01","claveAcceso":"0710202601012345678900110010010000001231234567811","eventType":"document.authorized","resourceId":"3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f","occurredAtUtc":"2026-10-07T15:04:05.1234567Z"}';

// En tu endpoint usa time() en lugar del instante fijo del vector.
var_dump(WebhookSignature::verify($secreto, $cabecera, $cuerpo, 1791385446, 300));
import com.ecuafact.sdk.WebhookSignature;
import java.time.Instant;

public class Firma {

    public static void main(String[] args) {
        String secreto = "c2VjcmV0by1kZS1wcnVlYmFzLW5vLXVzYXItMzJieXQ=";
        String cabecera = "t=1791385446,v1=3e2365076d2a218f96f8845e726567b874ad07c63304e217977cfc6368605d20";
        String cuerpo = """
            {"idOperacion":"3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f","estado":"autorizado","codEstado":2001,"errores":[],"tipoDocumento":"01","claveAcceso":"0710202601012345678900110010010000001231234567811","eventType":"document.authorized","resourceId":"3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f","occurredAtUtc":"2026-10-07T15:04:05.1234567Z"}""";
        // En tu endpoint usa Instant.now() en lugar del instante fijo del vector.
        System.out.println(WebhookSignature.verify(secreto, cabecera, cuerpo, Instant.ofEpochSecond(1791385446L), 300));
    }
}
# Guarda el cuerpo del vector 1 tal cual, sin salto de línea final.
printf '%s' '{"idOperacion":"3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f","estado":"autorizado","codEstado":2001,"errores":[],"tipoDocumento":"01","claveAcceso":"0710202601012345678900110010010000001231234567811","eventType":"document.authorized","resourceId":"3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f","occurredAtUtc":"2026-10-07T15:04:05.1234567Z"}' > evento.json
export ECUAFACT_WEBHOOK_SECRET='c2VjcmV0by1kZS1wcnVlYmFzLW5vLXVzYXItMzJieXQ='

# --ahora fija el instante del vector; con un webhook real, omítelo.
# Resultado esperado: valida si, motivo "Firma valida."
ecuafact webhooks verificar --firma "t=1791385446,v1=3e2365076d2a218f96f8845e726567b874ad07c63304e217977cfc6368605d20" --cuerpo @evento.json --ahora 1791385446

Esta tabla resume cómo se llama el verificador de cada SDK y qué parámetros recibe:

SDK Función Instante actual Tolerancia
.NET (Ecuafact.Sdk) Ecuafact.Sdk.Webhooks.WebhookSignature.Verify(secret, header, body, now, tolerance) DateTimeOffset now TimeSpan tolerance
Python (ecuafact) ecuafact.verify(secret, header, body, now=None, tolerance_seconds=300) segundos Unix; None = ahora segundos
Node.js (@ecuafact/sdk) verify(secret, header, body, now = new Date(), toleranceSeconds = 300) Date segundos
PHP (ecuafact/sdk) Ecuafact\Sdk\WebhookSignature::verify($secret, $header, $body, ?int $now = null, int $toleranceSeconds = 300) segundos Unix; null = ahora segundos
Java (com.ecuafact:sdk) com.ecuafact.sdk.WebhookSignature.verify(secret, header, body, Instant now, long toleranceSeconds) Instant segundos

Todos devuelven false, sin lanzar una excepción, si la cabecera falta o está mal formada, si la marca de tiempo está fuera de la tolerancia o si la firma no coincide. Todos aceptan v1 en mayúsculas o minúsculas y comparan en tiempo constante. En secret también aceptan una lista de secretos, y la entrega es válida si coincide con cualquiera de ellos, lo que te sirve durante la rotación del secreto.

Los SDK verifican también la firma de Standard Webhooks, y traen un verificador que recibe las cabeceras de la petición y acepta cualquiera de las dos firmas: comprueba Ecuafact-Signature y, si falta o no coincide, las cabeceras de Standard Webhooks. Es la forma recomendada de verificar con un SDK, porque funciona igual llegue la firma que llegue. Las mismas reglas valen para los dos: devuelven false sin lanzar una excepción, aceptan el secreto con o sin el prefijo whsec_ y aceptan una lista de secretos para la rotación.

SDK Solo Standard Webhooks Cualquiera de las dos firmas Evento tipado con cualquiera de las dos
.NET StandardWebhookSignature.Verify(secreto, id, timestamp, firma, cuerpo) WebhookSignature.VerificarEntrega(secretos, nombre => Request.Headers[nombre], cuerpo) WebhookEvent.ConstruirDesdeEntrega(secretos, nombre => Request.Headers[nombre], cuerpo)
Node.js verificarStandardWebhooks(secreto, { webhookId, webhookTimestamp, webhookSignature }, cuerpo) verificarWebhook(secreto, req.headers, cuerpo) construirEventoDesdeCabeceras(secreto, req.headers, cuerpo)
Python ecuafact.verificar_estandar(secreto, webhook_id, webhook_timestamp, webhook_signature, cuerpo) ecuafact.verificar_webhook(secreto, request.headers, cuerpo) ecuafact.construir_evento_webhook(secreto, request.headers, cuerpo)
PHP WebhookSignature::verificarStandardWebhooks($secreto, $id, $timestamp, $firma, $cuerpo) WebhookSignature::verificarCabeceras($secreto, getallheaders(), $cuerpo) WebhookEvent::construirDesdeCabeceras($secreto, getallheaders(), $cuerpo)
Java WebhookSignature.verificarEstandar(secreto, id, timestamp, firma, cuerpo) WebhookSignature.verificarCualquiera(secreto, cabeceras, cuerpo) (o request::getHeader) WebhookEvent.construirConCabeceras(secretos, cabeceras, cuerpo)

En todos, cuerpo es el cuerpo crudo de la petición, tal como llegó, y la tolerancia por defecto es de 300 segundos.

Vector de prueba#

Usa estos vectores para probar tu función de HMAC. En los dos, el cuerpo es una sola línea, sin salto de línea final. Como t es una fecha fija, tu verificación completa fallará por tolerancia si usas la hora actual. Por eso, prueba el cálculo del HMAC por separado o pasa el instante del vector, como hacen los ejemplos.

Vector 1: evento completo, con un secreto del mismo formato que los reales.

Dato Valor
Secreto c2VjcmV0by1kZS1wcnVlYmFzLW5vLXVzYXItMzJieXQ=
t 1791385446 (2026-10-07 15:04:06 UTC)
Cuerpo crudo {"idOperacion":"3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f","estado":"autorizado","codEstado":2001,"errores":[],"tipoDocumento":"01","claveAcceso":"0710202601012345678900110010010000001231234567811","eventType":"document.authorized","resourceId":"3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f","occurredAtUtc":"2026-10-07T15:04:05.1234567Z"}
Cadena firmada 1791385446. seguido del cuerpo crudo
v1 esperado 3e2365076d2a218f96f8845e726567b874ad07c63304e217977cfc6368605d20
Cabecera Ecuafact-Signature: t=1791385446,v1=3e2365076d2a218f96f8845e726567b874ad07c63304e217977cfc6368605d20

Vector 2: cuerpo mínimo.

Dato Valor
Secreto whsec_pruebas
t 1757341445
Cuerpo crudo {"eventType":"document.authorized","resourceId":"3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f"}
v1 esperado e3b03c6de58fd0565b83be8c2c83b0fb68dafe66edd06c568e57c5d48e992228
printf '%s' '1757341445.{"eventType":"document.authorized","resourceId":"3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f"}' \
  | openssl dgst -sha256 -hmac "whsec_pruebas"
# e3b03c6de58fd0565b83be8c2c83b0fb68dafe66edd06c568e57c5d48e992228

Si con el vector 1 obtienes uno de estos valores en lugar del esperado, la tabla te dice qué falla:

Obtienes Causa Corrección
219caea9414d73dfe03866573a5e60fe02135c95c119e74b79ccbc1255c324f1 Decodificaste el secreto como Base64. Usa los bytes UTF-8 del texto del secreto, sin decodificar.
68a67ed5142f10c742ad26a4b7c763e74443d564fba6032c1f66aae912692a65 Firmaste el JSON re-serializado, con ", " y ": " como separadores, que es el formato por defecto de json.dumps de Python. Firma el cuerpo crudo.
3E236507... (mayúsculas) Tu biblioteca devuelve el hexadecimal en mayúsculas, como hace Convert.ToHexString en .NET. Pasa el valor a minúsculas antes de comparar.

Standard Webhooks#

Cada entrega trae también las tres cabeceras de Standard Webhooks, un estándar abierto para firmar webhooks que ya usan otras plataformas y que tiene librerías oficiales en varios lenguajes. Puedes verificar cualquiera de las dos firmas: las dos cubren el mismo cuerpo, llegan en todas las entregas y se calculan con el mismo secreto. Si empiezas una integración nueva, te recomendamos el estándar, porque puedes verificarlo con una librería en lugar de escribir el código.

Cabecera Ejemplo Descripción
webhook-id 9b2e4f7a-1c3d-4e5f-8a6b-7c8d9e0f1a2b Identificador del evento. Es el mismo en todos los reintentos y en cada Reenviar, así que también te sirve para descartar duplicados.
webhook-timestamp 1791385446 Segundos Unix (UTC) en que se firmó esta entrega. Es el mismo valor que t en Ecuafact-Signature y cambia en cada reintento.
webhook-signature v1,rbz87ROH4WUgKHvxoJrwz+376xfbkN/F2sPyT/SPjP8= Lista de firmas separadas por espacios. Cada firma es v1, seguido del HMAC-SHA256 en Base64. Enviamos una sola, pero lee la lista completa y acepta la entrega si coincide cualquiera.

La firma es el HMAC-SHA256 de esta cadena:

<webhook-id> + "." + <webhook-timestamp> + "." + <cuerpo crudo>

Atención

La clave del HMAC es distinta en cada esquema. En Ecuafact-Signature la clave son los bytes UTF-8 del texto del secreto. En Standard Webhooks la clave son los 32 bytes que resultan de decodificar el secreto como Base64. Las librerías del estándar aceptan el secreto tal como lo muestra el portal o con el prefijo whsec_ delante (whsec_c2VjcmV0by1k...), y lo decodifican por ti.

Para verificar una entrega con el estándar, tu servidor sigue estos pasos:

  1. Lee las tres cabeceras. Si falta alguna, rechaza la entrega con un 401.
  2. Compara webhook-timestamp con tu reloj y rechaza la entrega si la diferencia supera tu tolerancia, que te recomendamos fijar en 300 segundos.
  3. Quita el prefijo whsec_ del secreto, si lo tiene, y decodifícalo como Base64 para obtener la clave.
  4. Calcula el HMAC-SHA256 de webhook-id + "." + webhook-timestamp + "." + cuerpo_crudo en bytes UTF-8 y codifícalo en Base64.
  5. Separa webhook-signature por espacios y, de cada firma que empiece con v1,, compara lo que sigue a la coma con tu resultado, usando una comparación de tiempo constante. Si ninguna coincide, rechaza la entrega.
  6. Solo ahora interpreta el JSON y procesa el evento.

Cada ejemplo verifica el vector 3 e imprime true (o True en Python). Los SDK verifican esta firma por sí mismos. En el modo SDK, las pestañas de Node.js y Python muestran además las librerías oficiales del estándar, que comprueban la marca de tiempo con la hora actual y por eso no aceptan el vector de fecha fija; con un webhook real devuelven el evento ya interpretado y lanzan WebhookVerificationError si la firma no coincide. La pestaña CLI verifica las mismas cabeceras con ecuafact webhooks verificar.

# Herramienta de diagnostico: no compara en tiempo constante. No la uses en produccion.
SECRETO='c2VjcmV0by1kZS1wcnVlYmFzLW5vLXVzYXItMzJieXQ='
ID='9b2e4f7a-1c3d-4e5f-8a6b-7c8d9e0f1a2b'
MARCA='1791385446'
FIRMAS='v1,rbz87ROH4WUgKHvxoJrwz+376xfbkN/F2sPyT/SPjP8='
CUERPO='{"idOperacion":"3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f","estado":"autorizado","codEstado":2001,"errores":[],"tipoDocumento":"01","claveAcceso":"0710202601012345678900110010010000001231234567811","eventType":"document.authorized","resourceId":"3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f","occurredAtUtc":"2026-10-07T15:04:05.1234567Z"}'

CLAVE_HEX=$(printf '%s' "${SECRETO#whsec_}" | base64 -d | od -An -tx1 | tr -d ' \n')
ESPERADO=$(printf '%s' "$ID.$MARCA.$CUERPO" | openssl dgst -sha256 -mac HMAC -macopt hexkey:"$CLAVE_HEX" -binary | base64)
case " $FIRMAS " in *" v1,$ESPERADO "*) echo "true" ;; *) echo "false" ;; esac
using System.Security.Cryptography;
using System.Text;

const string Secreto = "c2VjcmV0by1kZS1wcnVlYmFzLW5vLXVzYXItMzJieXQ=";
const string Id = "9b2e4f7a-1c3d-4e5f-8a6b-7c8d9e0f1a2b";
const string Marca = "1791385446";
const string Firmas = "v1,rbz87ROH4WUgKHvxoJrwz+376xfbkN/F2sPyT/SPjP8=";
const string Cuerpo = """{"idOperacion":"3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f","estado":"autorizado","codEstado":2001,"errores":[],"tipoDocumento":"01","claveAcceso":"0710202601012345678900110010010000001231234567811","eventType":"document.authorized","resourceId":"3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f","occurredAtUtc":"2026-10-07T15:04:05.1234567Z"}""";

// En tu endpoint: ahora = DateTimeOffset.UtcNow.ToUnixTimeSeconds()
Console.WriteLine(VerificarEstandar(Secreto, Id, Marca, Firmas, Cuerpo, ahora: 1791385446, toleranciaSegundos: 300));

static bool VerificarEstandar(string secreto, string id, string marca, string firmas, string cuerpoCrudo, long ahora, long toleranciaSegundos)
{
    if (!long.TryParse(marca, out long t) || Math.Abs(ahora - t) > toleranciaSegundos)
    {
        return false;
    }
    byte[] clave = Convert.FromBase64String(secreto.StartsWith("whsec_", StringComparison.Ordinal) ? secreto[6..] : secreto);
    byte[] esperado = HMACSHA256.HashData(clave, Encoding.UTF8.GetBytes(id + "." + marca + "." + cuerpoCrudo));
    foreach (string firma in firmas.Split(' ', StringSplitOptions.RemoveEmptyEntries))
    {
        byte[] recibida = new byte[firma.Length];
        if (firma.StartsWith("v1,", StringComparison.Ordinal)
            && Convert.TryFromBase64String(firma[3..], recibida, out int largo)
            && CryptographicOperations.FixedTimeEquals(recibida.AsSpan(0, largo), esperado))
        {
            return true;
        }
    }
    return false;
}
import base64
import hashlib
import hmac
import time

SECRETO = "c2VjcmV0by1kZS1wcnVlYmFzLW5vLXVzYXItMzJieXQ="
ID = "9b2e4f7a-1c3d-4e5f-8a6b-7c8d9e0f1a2b"
MARCA = "1791385446"
FIRMAS = "v1,rbz87ROH4WUgKHvxoJrwz+376xfbkN/F2sPyT/SPjP8="
CUERPO = ('{"idOperacion":"3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f","estado":"autorizado","codEstado":2001,"errores":[],"tipoDocumento":"01",'
          '"claveAcceso":"0710202601012345678900110010010000001231234567811",'
          '"eventType":"document.authorized","resourceId":"3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f",'
          '"occurredAtUtc":"2026-10-07T15:04:05.1234567Z"}')


def verificar_estandar(secreto, id_evento, marca, firmas, cuerpo_crudo, ahora=None, tolerancia=300):
    if not marca.isdigit():
        return False
    ahora = int(time.time()) if ahora is None else ahora
    if abs(ahora - int(marca)) > tolerancia:
        return False
    clave = base64.b64decode(secreto.removeprefix("whsec_"))
    firmado = f"{id_evento}.{marca}.{cuerpo_crudo}".encode("utf-8")
    esperado = base64.b64encode(hmac.new(clave, firmado, hashlib.sha256).digest()).decode()
    return any(f.startswith("v1,") and hmac.compare_digest(f[3:], esperado) for f in firmas.split(" "))


# En tu endpoint omite "ahora" para usar la hora actual.
print(verificar_estandar(SECRETO, ID, MARCA, FIRMAS, CUERPO, ahora=1791385446))
// Node.js 18 o superior. Guarda como firma-estandar.mjs y ejecuta: node firma-estandar.mjs
import { createHmac, timingSafeEqual } from 'node:crypto';

const SECRETO = 'c2VjcmV0by1kZS1wcnVlYmFzLW5vLXVzYXItMzJieXQ=';
const ID = '9b2e4f7a-1c3d-4e5f-8a6b-7c8d9e0f1a2b';
const MARCA = '1791385446';
const FIRMAS = 'v1,rbz87ROH4WUgKHvxoJrwz+376xfbkN/F2sPyT/SPjP8=';
const CUERPO = '{"idOperacion":"3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f","estado":"autorizado","codEstado":2001,"errores":[],"tipoDocumento":"01","claveAcceso":"0710202601012345678900110010010000001231234567811","eventType":"document.authorized","resourceId":"3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f","occurredAtUtc":"2026-10-07T15:04:05.1234567Z"}';

function verificarEstandar(secreto, id, marca, firmas, cuerpoCrudo, ahora = Math.floor(Date.now() / 1000), tolerancia = 300) {
  if (!/^\d+$/.test(marca) || Math.abs(ahora - Number(marca)) > tolerancia) return false;
  const clave = Buffer.from(secreto.replace(/^whsec_/, ''), 'base64');
  const esperado = createHmac('sha256', clave).update(`${id}.${marca}.${cuerpoCrudo}`, 'utf8').digest();
  return firmas.split(' ').some((firma) => {
    if (!firma.startsWith('v1,')) return false;
    const recibida = Buffer.from(firma.slice(3), 'base64');
    return recibida.length === esperado.length && timingSafeEqual(recibida, esperado);
  });
}

// En tu endpoint omite "ahora" para usar la hora actual.
console.log(verificarEstandar(SECRETO, ID, MARCA, FIRMAS, CUERPO, 1791385446));
<?php
$secreto = 'c2VjcmV0by1kZS1wcnVlYmFzLW5vLXVzYXItMzJieXQ=';
$id = '9b2e4f7a-1c3d-4e5f-8a6b-7c8d9e0f1a2b';
$marca = '1791385446';
$firmas = 'v1,rbz87ROH4WUgKHvxoJrwz+376xfbkN/F2sPyT/SPjP8=';
$cuerpo = '{"idOperacion":"3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f","estado":"autorizado","codEstado":2001,"errores":[],"tipoDocumento":"01","claveAcceso":"0710202601012345678900110010010000001231234567811","eventType":"document.authorized","resourceId":"3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f","occurredAtUtc":"2026-10-07T15:04:05.1234567Z"}';

function verificarEstandar(string $secreto, string $id, string $marca, string $firmas, string $cuerpoCrudo, ?int $ahora = null, int $tolerancia = 300): bool
{
    if (!ctype_digit($marca) || abs(($ahora ?? time()) - (int) $marca) > $tolerancia) {
        return false;
    }
    $clave = base64_decode(preg_replace('/^whsec_/', '', $secreto), true);
    if ($clave === false) {
        return false;
    }
    $esperado = base64_encode(hash_hmac('sha256', $id . '.' . $marca . '.' . $cuerpoCrudo, $clave, true));
    foreach (explode(' ', $firmas) as $firma) {
        if (str_starts_with($firma, 'v1,') && hash_equals($esperado, substr($firma, 3))) {
            return true;
        }
    }
    return false;
}

// En tu endpoint omite $ahora para usar la hora actual.
var_dump(verificarEstandar($secreto, $id, $marca, $firmas, $cuerpo, 1791385446));
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.util.Base64;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

public class FirmaEstandar {

    public static void main(String[] args) throws Exception {
        String secreto = "c2VjcmV0by1kZS1wcnVlYmFzLW5vLXVzYXItMzJieXQ=";
        String id = "9b2e4f7a-1c3d-4e5f-8a6b-7c8d9e0f1a2b";
        String marca = "1791385446";
        String firmas = "v1,rbz87ROH4WUgKHvxoJrwz+376xfbkN/F2sPyT/SPjP8=";
        String cuerpo = """
            {"idOperacion":"3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f","estado":"autorizado","codEstado":2001,"errores":[],"tipoDocumento":"01","claveAcceso":"0710202601012345678900110010010000001231234567811","eventType":"document.authorized","resourceId":"3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f","occurredAtUtc":"2026-10-07T15:04:05.1234567Z"}""";
        // En tu endpoint: ahora = java.time.Instant.now().getEpochSecond()
        System.out.println(verificarEstandar(secreto, id, marca, firmas, cuerpo, 1791385446L, 300));
    }

    static boolean verificarEstandar(String secreto, String id, String marca, String firmas, String cuerpoCrudo, long ahora, long tolerancia) throws Exception {
        if (!marca.matches("\\d+") || Math.abs(ahora - Long.parseLong(marca)) > tolerancia) {
            return false;
        }
        byte[] clave = Base64.getDecoder().decode(secreto.startsWith("whsec_") ? secreto.substring(6) : secreto);
        Mac mac = Mac.getInstance("HmacSHA256");
        mac.init(new SecretKeySpec(clave, "HmacSHA256"));
        byte[] esperado = mac.doFinal((id + "." + marca + "." + cuerpoCrudo).getBytes(StandardCharsets.UTF_8));
        for (String firma : firmas.split(" ")) {
            if (!firma.startsWith("v1,")) {
                continue;
            }
            try {
                if (MessageDigest.isEqual(Base64.getDecoder().decode(firma.substring(3)), esperado)) {
                    return true;
                }
            } catch (IllegalArgumentException e) {
                // Firma que no es Base64: se ignora y se prueba la siguiente.
            }
        }
        return false;
    }
}
// Librería oficial del estándar: npm install standardwebhooks express
// Guarda como servidor.mjs y ejecuta: node servidor.mjs
import express from 'express';
import { Webhook, WebhookVerificationError } from 'standardwebhooks';

const app = express();
const verificador = new Webhook(process.env.ECUAFACT_WEBHOOK_SECRET);

// express.raw entrega el cuerpo crudo, sin interpretar el JSON.

app.post('/webhooks', express.raw({ type: 'application/json' }), (req, res) => {
  let evento;
  try {
    // Comprueba la firma y la marca de tiempo, y devuelve el JSON interpretado.
    evento = verificador.verify(req.body.toString('utf8'), req.headers);
  } catch (error) {
    if (error instanceof WebhookVerificationError) return res.sendStatus(401);
    throw error;
  }
  // Procesa evento.eventType y responde 2xx.
  res.sendStatus(200);
});

app.listen(3000);
# Librería oficial del estándar: pip install standardwebhooks flask
# Guarda como servidor.py y ejecuta: flask --app servidor run --port 3000
# request.get_data() devuelve el cuerpo crudo, sin interpretar el JSON.
import os

from flask import Flask, request
from standardwebhooks.webhooks import Webhook, WebhookVerificationError

app = Flask(__name__)
verificador = Webhook(os.environ["ECUAFACT_WEBHOOK_SECRET"])


@app.post("/webhooks")
def webhooks():
    try:
        # Comprueba la firma y la marca de tiempo, y devuelve el JSON interpretado.
        evento = verificador.verify(request.get_data(as_text=True), dict(request.headers))
    except WebhookVerificationError:
        return "", 401
    # Procesa evento["eventType"] y responde 2xx.
    return "", 200
# Guarda el cuerpo del vector 3 tal cual, sin salto de línea final.
printf '%s' '{"idOperacion":"3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f","estado":"autorizado","codEstado":2001,"errores":[],"tipoDocumento":"01","claveAcceso":"0710202601012345678900110010010000001231234567811","eventType":"document.authorized","resourceId":"3f1c8c1e-6f2a-4b7e-9c3d-2a1b0c9d8e7f","occurredAtUtc":"2026-10-07T15:04:05.1234567Z"}' > evento.json
export ECUAFACT_WEBHOOK_SECRET='c2VjcmV0by1kZS1wcnVlYmFzLW5vLXVzYXItMzJieXQ='

# --ahora fija el instante del vector; con un webhook real, omítelo.
# Resultado esperado: valida si, esquema standard-webhooks, motivo "Firma valida."
ecuafact webhooks verificar --webhook-id 9b2e4f7a-1c3d-4e5f-8a6b-7c8d9e0f1a2b --webhook-timestamp 1791385446 --webhook-signature "v1,rbz87ROH4WUgKHvxoJrwz+376xfbkN/F2sPyT/SPjP8=" --cuerpo @evento.json --ahora 1791385446

El estándar publica librerías oficiales para más lenguajes, por ejemplo Go, Ruby, Rust, Java y Kotlin, que aceptan el secreto de la misma forma. Las encuentras en standardwebhooks.com.

Vector 3: Standard Webhooks#

Usa el mismo secreto y el mismo cuerpo del vector 1.

Dato Valor
Secreto c2VjcmV0by1kZS1wcnVlYmFzLW5vLXVzYXItMzJieXQ=, o whsec_c2VjcmV0by1kZS1wcnVlYmFzLW5vLXVzYXItMzJieXQ= en una librería del estándar
webhook-id 9b2e4f7a-1c3d-4e5f-8a6b-7c8d9e0f1a2b
webhook-timestamp 1791385446 (2026-10-07 15:04:06 UTC)
Cadena firmada 9b2e4f7a-1c3d-4e5f-8a6b-7c8d9e0f1a2b.1791385446. seguido del cuerpo crudo
webhook-signature esperada v1,rbz87ROH4WUgKHvxoJrwz+376xfbkN/F2sPyT/SPjP8=

Si obtienes v1,EtTOf62C... en lugar del valor esperado, usaste el texto del secreto como clave sin decodificarlo, que es lo que pide Ecuafact-Signature pero no el estándar.

Tolerancia de tiempo#

La tolerancia es la diferencia máxima que aceptas entre la marca de tiempo de la firma y el reloj de tu servidor. Estas son las reglas para elegirla y aplicarla:

  • Rechaza la entrega si |ahora - t| supera tu tolerancia. Te recomendamos 300 segundos, es decir, 5 minutos, que es el valor por defecto de los SDK.
  • Cada reintento se firma de nuevo con un t actual, así que la tolerancia no rechaza reintentos legítimos aunque el evento original sea de horas antes. Para saber cuándo ocurrió el hecho, usa el occurredAtUtc del cuerpo y no t.
  • Mantén el reloj de tu servidor sincronizado por NTP. Un reloj desfasado más que la tolerancia rechaza todas las entregas, y después de 8 fallos consecutivos el destino se pausa.
  • No uses una tolerancia menor a 60 segundos, porque una entrega puede tardar más que eso en llegar a tu servidor.

Rotación de secreto#

Rota el secreto si se expuso, por ejemplo porque quedó en un log o en un repositorio, o como práctica periódica. Para hacerlo, pulsa Rotar secreto en el destino, en Integración > Eventos. También puedes rotarlo por API con POST /v1/webhooks/destinos/{id}/rotar-secreto, que devuelve el secreto nuevo en secretoUnaVez, como se explica en Webhooks.

Al rotar, recibes el secreto nuevo una sola vez y todas las entregas siguientes se firman solo con el secreto nuevo, incluidos los reintentos de eventos anteriores. Como no enviamos una segunda firma con el secreto anterior, sigue estos pasos para no rechazar entregas durante el cambio:

  1. Prepara tu servidor para aceptar una lista de secretos, de modo que la entrega sea válida si la firma coincide con cualquiera de ellos. Los ejemplos de abajo muestran cómo.
  2. Pulsa Rotar secreto y copia el secreto nuevo.
  3. Agrega el secreto nuevo a la lista, sin quitar el anterior, y publica el cambio cuanto antes.
  4. Las entregas que lleguen entre la rotación y tu publicación fallan la verificación, y las seguimos reintentando con esperas crecientes. Revisa en Entregas que vuelvan a mostrar HTTP 200.
  5. Cuando las entregas se firmen correctamente con el secreto nuevo, quita el anterior de la lista.
// Acepta la entrega si la firma coincide con alguno de los secretos vigentes.
string[] secretos = { Environment.GetEnvironmentVariable("ECUAFACT_WEBHOOK_SECRET")!,
                      Environment.GetEnvironmentVariable("ECUAFACT_WEBHOOK_SECRET_ANTERIOR") ?? "" };
long ahora = DateTimeOffset.UtcNow.ToUnixTimeSeconds();
bool valido = secretos.Any(s => s.Length > 0 && Verificar(s, cabecera, cuerpoCrudo, ahora, 300));
# Acepta la entrega si la firma coincide con alguno de los secretos vigentes.
secretos = [s for s in (os.environ.get("ECUAFACT_WEBHOOK_SECRET"), os.environ.get("ECUAFACT_WEBHOOK_SECRET_ANTERIOR")) if s]
valido = any(verificar(s, cabecera, cuerpo_crudo) for s in secretos)
// Acepta la entrega si la firma coincide con alguno de los secretos vigentes.
const secretos = [process.env.ECUAFACT_WEBHOOK_SECRET, process.env.ECUAFACT_WEBHOOK_SECRET_ANTERIOR].filter(Boolean);
const valido = secretos.some((s) => verificar(s, cabecera, cuerpoCrudo));
<?php
// Acepta la entrega si la firma coincide con alguno de los secretos vigentes.
$secretos = array_filter([getenv('ECUAFACT_WEBHOOK_SECRET'), getenv('ECUAFACT_WEBHOOK_SECRET_ANTERIOR')]);
$valido = false;
foreach ($secretos as $s) {
    $valido = $valido || verificar($s, $cabecera, $cuerpoCrudo);
}
// Acepta la entrega si la firma coincide con alguno de los secretos vigentes.
long ahora = java.time.Instant.now().getEpochSecond();
boolean valido = false;
for (String s : new String[] { System.getenv("ECUAFACT_WEBHOOK_SECRET"), System.getenv("ECUAFACT_WEBHOOK_SECRET_ANTERIOR") }) {
    if (s != null && !s.isEmpty() && verificar(s, cabecera, cuerpoCrudo, ahora, 300)) {
        valido = true;
    }
}

Estos fragmentos usan la función verificar de la sección Verificación y las variables cabecera y cuerpoCrudo de tu endpoint, que en Python se llama cuerpo_crudo. Si verificas con una librería de Standard Webhooks, que recibe un solo secreto, crea un verificador por cada secreto vigente y acepta la entrega si cualquiera de ellos la valida.

Atención

Si sospechas que el secreto se filtró, rótalo de inmediato y retira el anterior en cuanto publiques el nuevo, porque mientras lo aceptes, quien lo tenga puede enviarte eventos falsos.

Errores frecuentes#

Si la verificación falla, busca el síntoma en esta tabla.

Error Síntoma Corrección
Cuerpo re-serializado Todas las firmas fallan aunque el secreto sea correcto. Lee el cuerpo crudo antes de cualquier deserialización (Request.Body, el middleware raw de Express.js, request.get_data(), php://input, @RequestBody byte[]).
Cuerpo modificado en el camino Las firmas fallan solo detrás de cierto proxy, WAF o middleware. Revisa que nada entre nuestro envío y tu código reescriba el cuerpo, por ejemplo al minificarlo, reindentarlo, cambiar su codificación o agregarle un salto de línea final.
Codificación incorrecta La verificación falla con algunos cuerpos y no con otros. Decodifica el cuerpo como UTF-8, o firma directamente los bytes, y convierte la cadena firmada a bytes UTF-8. No uses Latin-1 ni la codificación por defecto del sistema.
Secreto decodificado como Base64 La firma de Ecuafact-Signature es distinta en todos los casos; con el vector 1 obtienes 219caea9.... Usa el texto del secreto como clave, en UTF-8.
Secreto sin decodificar en Standard Webhooks La firma de webhook-signature es distinta en todos los casos; con el vector 3 obtienes v1,EtTOf62C.... Quita el prefijo whsec_ si lo tiene y decodifica el secreto como Base64, o usa una librería del estándar.
Cadena del estándar mal armada webhook-signature no coincide aunque la clave sea la correcta. Firma webhook-id + "." + webhook-timestamp + "." + cuerpo_crudo, con los valores de las cabeceras.
Secreto con espacios o salto de línea La firma es distinta en todos los casos. Al copiar el secreto del portal o leerlo de un archivo, quita los espacios y saltos de línea del inicio y del final.
Hexadecimal en mayúsculas La comparación falla aunque el valor sea correcto. Convierte tu resultado y v1 a minúsculas antes de comparar.
Comparación no constante La verificación funciona, pero == o equals revela por tiempo cuántos caracteres coinciden. Usa CryptographicOperations.FixedTimeEquals, hmac.compare_digest, crypto.timingSafeEqual, hash_equals o MessageDigest.isEqual.
Cadena firmada mal armada La firma es distinta porque falta el punto, usas tu propio reloj en lugar de t o pones el cuerpo antes de t. Firma exactamente t + "." + cuerpo_crudo, con el t de la cabecera.
Lectura posicional de la cabecera La verificación falla si cambia el orden o se agrega una parte nueva. Lee t y v1 por su nombre.
Reloj desfasado Todas las entregas fallan por tolerancia. Sincroniza el reloj por NTP y usa una tolerancia de 300 segundos.
Secreto de otro destino o ambiente Fallan todas las entregas de un destino. Cada destino, y cada ambiente, tiene su propio secreto. Usa el del destino que recibe.

Siguientes pasos#

  • Webhooks: configura el destino y conoce los eventos, los reintentos y cómo descartar duplicados.
  • SDK .NET: instala el SDK que incluye el verificador de firma.
  • Seguimiento de una operación: confirma el estado de una operación si dudas de un evento.
No se pudo completar la operación. Recargar ✕

Conexión con el servidor

Restableciendo la conexión…

Intento 1 de 5.

No se pudo conectar. Revisa tu conexión y vuelve a intentarlo.

La sesión ya no está disponible. Recarga la página para continuar.

La sesión está en pausa. Puedes reanudarla para continuar.

No se pudo reanudar la sesión. Vuelve a intentarlo o recarga la página.

Al recargar se perderán los cambios que no hayas guardado.