Avisos por webhook de Docuten eArchiving — contrato v1

1. Resumen

Docuten eArchiving avisa a su sistema, sin que tenga que consultar, de dos cosas que le pasan a una ingesta:

• ingest.archived: el AIP se ha archivado y sellado.
• ingest.failed: la ingesta ha fallado, con el motivo del catálogo de errores (docs/api/ingest-error-codes.md).

El aviso es un POST con un cuerpo JSON firmado con HMAC-SHA256 a la URL que el administrador de su organización configura una sola vez (§2). Cada organización (tenant) tiene un webhook.

Qué tiene que hacer su receptor:

1. Exponer un endpoint https que acepte POST con Content-Type: application/json.
2. Verificar la firma de cada petición antes de fiarse del cuerpo (§6).
3. Responder 2xx en menos de 10 segundos cuando haya recibido el aviso. Cualquier otra respuesta se reintenta (§7).
4. Deduplicar por eventId: la entrega es «al menos una vez» y puede repetirse (§7).

2. Configurar el webhook

La configuración la gestiona el administrador del tenant (TENANT_ADMIN del propio tenant) o un PLATFORM_SUPER_ADMIN. El tenant sale siempre del claim tenant_id del token: no hay ningún identificador de tenant en las rutas, y no se puede configurar el webhook de otro tenant.

2.1 Alta

curl -X PUT https://<host>/api/v1/tenant/webhook \
  -H "Authorization: Bearer <token de un TENANT_ADMIN>" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://integraciones.ejemplo.com/hooks/earchiving" }'

Respuesta 201:

{
  "url": "https://integraciones.ejemplo.com/hooks/earchiving",
  "enabled": true,
  "createdAt": "2026-11-04T09:30:00Z",
  "updatedAt": "2026-11-04T09:30:00Z",
  "secret": "000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f"
}

2.2 El secreto se muestra una sola vez

secret son 64 caracteres hexadecimales (32 bytes aleatorios) y aparecen solo en la respuesta del alta y en la de la rotación, con Cache-Control: no-store. Guárdelo en su gestor de secretos al recibirlo: el servicio lo conserva cifrado y no puede volver a mostrárselo. Si lo pierde, rótelo.

2.3 Rotación con solapamiento de 24 h

POST /api/v1/tenant/webhook/secret/rotate genera un secreto nuevo y lo devuelve. El secreto anterior sigue firmando durante 24 h (previousSecretValidUntil): en ese periodo cada aviso lleva dos firmas v1= (§5), de modo que su receptor puede cambiar de secreto sin perder avisos. Pasadas las 24 h, solo queda el secreto nuevo. Una segunda rotación dentro del solapamiento sustituye al secreto anterior.

2.4 Cambiar o borrar la URL

Cambiar la URL con PUT conserva el secreto. Cada alta, cambio de URL, rotación y borrado queda en el log de auditoría del tenant (solo con el host de la URL y nunca con el secreto).

3. Reglas de la URL

La URL se valida al aceptarla y otra vez en cada envío (la resolución DNS se comprueba en el momento de conectar, de modo que un nombre que cambie de destino después del alta tampoco pasa).

• Solo https. Sin credenciales en la URL (https://usuario:clave@… se rechaza).
• Longitud máxima: 2048 caracteres.
• Destinos vedados, tanto si la URL lleva el literal como si el nombre resuelve a ellos: IPv4 0.0.0.0/8, 10.0.0.0/8, 100.64.0.0/10 (CGNAT), 127.0.0.0/8, 169.254.0.0/16 (incluye los metadatos de nube 169.254.169.254), 172.16.0.0/12, 192.0.0.0/24, 192.0.2.0/24, 192.168.0.0/16, 198.18.0.0/15, 198.51.100.0/24, 203.0.113.0/24, 168.63.129.16/32, 224.0.0.0/4 y 240.0.0.0/4; IPv6 ::, ::1, 100::/64, 2001:db8::/32, 64:ff9b:1::/48, fe80::/10, fec0::/10, fc00::/7 y ff00::/8, y las direcciones IPv6 que embeben una IPv4 vedada (::ffff:a.b.c.d, ::ffff:0:a.b.c.d, 64:ff9b::/96, 2002::/16).
• No se siguen redirecciones: una respuesta 3xx cuenta como fallo de entrega (REDIRECT_NOT_FOLLOWED). Configure la URL final.
• Timeouts: 5 s para conectar y 10 s para recibir la respuesta. Un receptor que tarda más cuenta como un intento fallido (TIMEOUT).
• El puerto de destino no se restringe. Limitarlo es un endurecimiento posible que la fase 06.6 no incluye.

Una URL que no cumple se rechaza con 400, errorCode WEBHOOK_URL_REJECTED y un reason de un conjunto cerrado: MALFORMED, URL_TOO_LONG, SCHEME_NOT_HTTPS, USERINFO_PRESENT, HOST_MISSING, HOST_UNRESOLVABLE o DESTINATION_FORBIDDEN. La respuesta no repite la URL ni la dirección resuelta.

4. Eventos

Todos los avisos son JSON con schemaVersion "1". Las fechas son ISO-8601 en UTC con milisegundos (2026-11-04T09:30:00.123Z). El orden de los campos es el de las tablas y es estable. Su receptor debe ignorar los campos que no conozca (§10).

Campos comunes: schemaVersion, eventId, eventType, occurredAt y sipId.

4.1 ingest.archived

El AIP se ha archivado: la saga ha terminado entera y el AIP está sellado y almacenado.

aipHash:

{
  "schemaVersion": "1",
  "eventId": "6f1c2a52-5d1f-4a0e-9c43-0b4f8a7d2e11",
  "eventType": "ingest.archived",
  "occurredAt": "2026-11-04T09:31:07.482Z",
  "sipId": "0b8e9f6a-3f6d-4c1e-8b54-2a7e61d0c9a3",
  "aipId": "d3f7a1c4-91b2-3e58-a6d0-4c2b8e5f7a19",
  "aipHash": {
    "algorithm": "SHA-256",
    "value": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"
  },
  "sealedAt": "2026-11-04T09:31:05.000Z"
}

Qué es sealedAt. Es el genTime del token TSA del sello n.º 2: la fecha que certifica la autoridad de sellado de tiempo cualificada sobre el hash del AIP completo. No es la fecha interna del XML de atestación (esa es el reloj local del servicio, se firma antes y difiere en segundos). Para cualquier uso probatorio, use sealedAt.

Otras notas:

• Un job en DEAD_LETTER que se reanuda y termina bien emite después su ingest.archived.
• Si el AIP se archiva pero su indexado en el catálogo queda pendiente, el aviso ingest.archived se envía igualmente: el archivado y el sellado son lo que el aviso garantiza.

4.2 ingest.failed

La ingesta ha fallado en segundo plano. El motivo sale solo del catálogo de errores publicado (docs/api/ingest-error-codes.md): el aviso nunca incluye mensajes de excepción, trazas ni rutas.

{
  "schemaVersion": "1",
  "eventId": "2b9e7d40-8c5a-4f33-a1d6-7e0c94b5f8a2",
  "eventType": "ingest.failed",
  "occurredAt": "2026-11-04T09:31:07.482Z",
  "sipId": "0b8e9f6a-3f6d-4c1e-8b54-2a7e61d0c9a3",
  "status": "FAILED",
  "errorCode": "CSIP_NONCONFORMANT",
  "errorClass": "REJECTED",
  "businessMessage": "El paquete no cumple la especificación E-ARK CSIP.",
  "catalogVersion": "1.3.0",
  "failedStep": "SIP_VALIDATED"
}

status:

• FAILED: un paso de la saga falló.
• DEAD_LETTER: un sellado cualificado agotó sus reintentos. Docuten decide si reanuda la ingesta.
• LAUNCH_FAILED: la saga no llegó a arrancar. Su errorCode es INTERNAL_PROCESSING_ERROR (el mismo que un FAILED de nivel de job).

5. Cabeceras y firma

Cada aviso lleva estas cabeceras, además de Content-Type: application/json:

La firma es:

v1 = hex( HMAC-SHA256( clave, t + "." + cuerpo_crudo ) )

• t es el instante de firma en segundos Unix, tal como aparece en la cabecera X-Earchiving-Signature.
• cuerpo_crudo son los bytes exactos que recibe. No lo vuelva a serializar.
• La clave es el texto hexadecimal del secreto, los 64 caracteres ASCII tal como se le mostraron, sin decodificarlos a bytes. Usar los 32 bytes decodificados da otra firma y la verificación falla.
• El resultado v1 va en hexadecimal en minúsculas.

Ejemplo con dos v1= durante la rotación (el secreto nuevo primero):

X-Earchiving-Signature: t=1700000000,v1=5e4794756710123db33aae34cfa3b61718e86dec195c06f4ef7b0b697e606bd4,v1=7598bb3f9283140d44336362e02ed888c07a4298ee51ae26effe0f978d89b391

6. Guía de verificación del receptor

Siga estos pasos, en este orden, con cada petición:

1. Lea el cuerpo crudo de la petición como bytes, antes de que ningún framework lo interprete como JSON.
2. Lea X-Earchiving-Signature y sepárela por comas: un t= y uno o más v1=. Si falta alguno, rechace.
3. Compruebe el desfase: rechace la petición si |ahora − t| supera 5 minutos (300 segundos). Así una petición capturada no se puede reutilizar más tarde.
4. Recompute HMAC-SHA256 con la clave igual al texto hexadecimal ASCII del secreto, sobre t + "." + cuerpo_crudo.
5. Compare en tiempo constante (MessageDigest.isEqual en Java, hmac.compare_digest en Python) el resultado con cada v1 recibido. Acepte si coincide cualquiera: durante la rotación hay dos y su receptor puede tener solo el secreto viejo o solo el nuevo.
6. Si la firma es válida, deduplique por eventId y responda 2xx.

6.1 Vector conocido

Compruebe su implementación con este vector antes de ponerla en producción:

Equivale a:

printf '1700000000.{"a":1}' | openssl dgst -sha256 -hmac 000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f

Un segundo vector, con el secreto 202122…3f y el mismo t y cuerpo, da 7598bb3f9283140d44336362e02ed888c07a4298ee51ae26effe0f978d89b391.

6.2 Ejemplo en Java 21

import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.time.Instant;
import java.util.ArrayList;
import java.util.HexFormat;
import java.util.List;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

public final class WebhookVerifier {

    private static final long TOLERANCE_SECONDS = 300;

    private WebhookVerifier() {
    }

    /** {@code rawBody} son los bytes exactos recibidos; {@code secretHex} el texto de 64 caracteres. */
    public static boolean verify(String signatureHeader, byte[] rawBody, String secretHex, Instant now)
        throws Exception {
        Long timestamp = null;
        List<String> candidates = new ArrayList<>();
        for (String part : signatureHeader.split(",")) {
            if (part.startsWith("t=")) {
                try {
                    timestamp = Long.parseLong(part.substring(2));
                } catch (NumberFormatException e) {
                    return false;
                }
            } else if (part.startsWith("v1=")) {
                candidates.add(part.substring(3));
            }
        }
        if (timestamp == null || candidates.isEmpty()) {
            return false;
        }
        if (Math.abs(now.getEpochSecond() - timestamp) > TOLERANCE_SECONDS) {
            return false;
        }
        // La clave es el texto hex tal cual (bytes ASCII), SIN decodificar.
        byte[] key = secretHex.getBytes(StandardCharsets.US_ASCII);
        Mac mac = Mac.getInstance("HmacSHA256");
        mac.init(new SecretKeySpec(key, "HmacSHA256"));
        mac.update((timestamp + ".").getBytes(StandardCharsets.US_ASCII));
        mac.update(rawBody);
        byte[] expected = HexFormat.of().formatHex(mac.doFinal()).getBytes(StandardCharsets.US_ASCII);
        boolean match = false;
        for (String candidate : candidates) {
            match |= MessageDigest.isEqual(expected, candidate.getBytes(StandardCharsets.US_ASCII));
        }
        return match;
    }
}

6.3 Ejemplo en Python 3

import hashlib
import hmac
import time


def verify(signature_header: str, raw_body: bytes, secret_hex: str, now: int | None = None,
           tolerance_seconds: int = 300) -> bool:
    """Verifica X-Earchiving-Signature. `raw_body` son los bytes exactos recibidos."""
    now = int(time.time()) if now is None else now
    timestamp = None
    candidates = []
    for part in signature_header.split(","):
        if part.startswith("t="):
            try:
                timestamp = int(part[2:])
            except ValueError:
                return False
        elif part.startswith("v1="):
            candidates.append(part[3:])
    if timestamp is None or not candidates:
        return False
    if abs(now - timestamp) > tolerance_seconds:
        return False
    key = secret_hex.encode("ascii")  # el texto hex tal cual, SIN decodificar
    message = str(timestamp).encode("ascii") + b"." + raw_body
    expected = hmac.new(key, message, hashlib.sha256).hexdigest()
    matches = [hmac.compare_digest(expected, c) for c in candidates]
    return any(matches)

Los dos ejemplos devuelven true/True con el vector de §6.1 y t igual a la hora actual simulada, y false/False si el cuerpo cambia ({"a":2}) o si el desfase supera 300 segundos.

7. Entrega y reintentos

• La entrega es «al menos una vez». Un mismo aviso puede llegar más de una vez (por ejemplo, si su receptor procesó el aviso pero la respuesta 2xx se perdió). El servicio no garantiza «exactamente una vez». Su receptor debe ser idempotente y deduplicar por eventId (cuerpo) o X-Earchiving-Event-Id (cabecera), que se conservan idénticos en cada reintento.
• Solo una respuesta 2xx es correcta. Cualquier otra —3xx (no se sigue), 4xx, 5xx, error de conexión, de TLS o un timeout— cuenta como fallo y se reintenta, incluidos los 4xx.
• Calendario. Tras el intento inmediato, los reintentos se hacen a 1 min, 5 min, 15 min, 1 h, 3 h, 6 h y 12 h del intento anterior: 8 intentos en total, unas 22 horas. El servicio comprueba los avisos pendientes cada 30 segundos, así que el calendario tiene esa tolerancia.
• Estado terminal. Agotados los 8 intentos, la entrega pasa a FAILED y no se reintenta más. El registro de entregas (§8) la conserva con su último error. Docuten es avisado en su log, pero no hay reenvío manual: si su receptor estuvo caído más de 22 horas, reconcilie consultando el estado de las ingestas (GET /api/v1/ingest/jobs).
• El orden no está garantizado entre avisos distintos.
• Las entregas de varios tenants son independientes: el receptor lento de uno no retrasa a los demás.

8. Registro de entregas

GET /api/v1/tenant/webhook/deliveries lista las entregas del tenant, de la más reciente a la más antigua.

Parámetros (todos opcionales): status (PENDING, DELIVERED o FAILED), sipId, page (por defecto 0) y size (por defecto 20, de 1 a 100). Un filtro mal formado devuelve 400 con errorCode WEBHOOK_DELIVERY_FILTER_INVALID.

Cada elemento de content lleva: id, eventId, eventType, sipId, status, attemptCount, lastHttpStatus, lastError, createdAt, lastAttemptAt, nextAttemptAt y deliveredAt. Nunca lleva el cuerpo del aviso ni lo que respondió el receptor.

Estados:

• PENDING: encolada o a la espera de un reintento (nextAttemptAt).
• DELIVERED: el receptor respondió 2xx.
• FAILED: terminal (8 intentos agotados, o no había webhook configurado y habilitado).

Retención: 90 días. Las entregas terminadas (DELIVERED y FAILED) se borran pasados 90 días.

8.1 Códigos de lastError

lastError es un código corto de un conjunto cerrado, nunca texto libre:

9. Deprecación de X-Webhook-Url

Hasta ahora, POST /api/v1/ingest/sip y POST /api/v1/ingest/file aceptaban la cabecera X-Webhook-Url para recibir un aviso sin firma por petición. Ya no envía nada.

• La cabecera se acepta e ignora: sus envíos no fallan, pero no reciben ningún aviso a esa URL.
• La respuesta incluye Deprecation: @1793664000 (RFC 9745; la fecha es el 2026-11-03) y Link: <https://docs.docuten.com/earchiving/webhook-notifications>; rel="deprecation".

Cómo migrar:

1. Elija un endpoint https fijo para su organización e impleméntelo según §6.
2. Dé de alta el webhook (§2.1) y guarde el secreto.
3. Compruebe con una ingesta de prueba y consulte el registro de entregas (§8).
4. Deje de enviar X-Webhook-Url.

Las diferencias respecto al aviso antiguo: la URL es del tenant y no de cada petición, el cuerpo está firmado, lleva el motivo del fallo y el aipId y la huella del AIP, y hay un ingest.failed también para FAILED y LAUNCH_FAILED.

10. Compatibilidad

• Este contrato es v1. Los cambios futuros solo pueden ser aditivos (campos nuevos al final de un evento, valores nuevos documentados) o exigirán una schemaVersion nueva. Un campo, un nombre de cabecera o un algoritmo de firma existentes no cambian dentro de v1.
• Su receptor debe ignorar los campos desconocidos y tolerar valores nuevos de status, errorCode y errorClass (el catálogo de errores crece de forma aditiva).
• Hay un webhook por tenant, y no hay filtrado por tipo de evento: recibirá ingest.archived e ingest.failed. Distinga por eventType.