<!-- source_url: https://docs.mynexusapi.com/v1/guias/webhooks-firma | last_updated: 2026-11-13 -->

# 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.

> [!IMPORTANT]
> 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](#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](/v1/guias/webhooks#configurar-el-destino-en-el-portal).
- [ ] 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.

> [!WARNING]
> 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](#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`.

```bash
# 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"
```

```csharp
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()));
}
```

```python
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))
```

```javascript
// 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
<?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));
```

```java
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));
    }
}
```

```csharp-sdk
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);
```

```python-sdk
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))
```

```javascript-sdk
// 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-sdk
<?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));
```

```java-sdk
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));
    }
}
```

```bash-cli
# 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](#rotacion-de-secreto).

Los SDK verifican también la firma de
[Standard Webhooks](#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` |

```bash
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](https://www.standardwebhooks.com), 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>
```

> [!WARNING]
> 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](#vector-3-standard-webhooks) 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`.

```bash
# 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
```

```csharp
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;
}
```

```python
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))
```

```javascript
// 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
<?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));
```

```java
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;
    }
}
```

```javascript-sdk
// 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);
```

```python-sdk
# 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
```

```bash-cli
# 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](https://www.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](/v1/guias/webhooks#administrar-destinos-por-api).

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.

```csharp
// 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));
```

```python
# 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)
```

```javascript
// 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
<?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);
}
```

```java
// 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](#verificacion) 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](#standard-webhooks), que recibe un solo secreto, crea un
verificador por cada secreto vigente y acepta la entrega si cualquiera de ellos
la valida.

> [!WARNING]
> 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](/v1/guias/webhooks): configura el destino y conoce los eventos, los reintentos y cómo descartar duplicados.
- [SDK .NET](/v1/guias/sdk-dotnet): instala el SDK que incluye el verificador de firma.
- [Seguimiento de una operación](/v1/guias/consulta-operacion): confirma el estado de una operación si dudas de un evento.
