Webhook

De un vistazo

NextPDF Enterprise entrega eventos de trabajo a puntos de conexión de webhook por inquilino mediante HTTP POST, firma cada carga útil con una firma HMAC-SHA256, reintenta con retroceso exponencial (backoff) y encamina las entregas que fallan de forma permanente a una cola de carta muerta (dead-letter) para su inspección y reproducción. Esta página describe el comportamiento observable del webhook y el contrato público.

Disponibilidad y licencias

Esta capacidad se incluye en NextPDF Enterprise (nextpdf/enterprise) y se activa con un sobre de licencia de nivel Enterprise. Un despliegue sin ese derecho no carga las clases de la capacidad. Comparar ediciones y obtener una licencia.

La superficie de webhook es una capacidad base de Enterprise, disponible una vez instalado el paquete Enterprise; no hay ningún indicador por función independiente.

Descripción conceptual

Un inquilino registra una URL de devolución de llamada, un secreto de firma y una lista opcional de tipos de evento. Una lista de eventos vacía significa «suscribirse a todos los eventos». Los registros tienen un alcance estrictamente por inquilino: un inquilino solo puede ver y gestionar sus propios registros, y registrarse bajo un inquilino no coincidente se rechaza. Cancelar el registro desactiva el registro en lugar de eliminarlo, por lo que se preserva el historial; solo los registros activos reciben despachos.

Cuando se despacha un evento de trabajo para un inquilino, cada registro activo que se suscribe al tipo de evento recibe una entrega. La carga útil es un documento JSON estandarizado: un identificador de entrega único, el identificador de trabajo, el tipo de evento, los datos del evento, una marca de tiempo RFC 3339 y el identificador de inquilino. La entrega es un HTTP POST que transporta el cuerpo JSON y cuatro cabeceras: una firma HMAC-SHA256, una marca de tiempo en segundos unix, el identificador de entrega y el tipo de evento. La firma se calcula sobre la cadena base canónica {timestamp}.{body} con el secreto del registro, de modo que la cabecera de marca de tiempo queda criptográficamente ligada al cuerpo. El receptor recalcula el HMAC sobre la misma cadena base y rechaza las entregas cuya marca de tiempo cae fuera de una ventana de frescura aceptable, lo que acota la reproducción.

La entrega usa retroceso exponencial. Una respuesta 2xx es éxito. Una respuesta 4xx distinta de 429 se trata como un rechazo permanente y no se reintenta. Otros fallos —5xx, 429 o un error de conexión— se reintentan hasta el recuento de intentos de la directiva con un retardo que se duplica, con un tope en un máximo. Cuando se agotan todos los intentos, la entrega se registra en una cola de carta muerta en memoria con la carga útil original, el recuento de intentos, el último error y el último estado HTTP; una entrada de carta muerta puede marcarse como reproducida. Se incluyen dos directivas de reintentos: una default (5 intentos, base 1 s, tope 5 min) y una aggressive (10 intentos, base 2 s, tope 10 min).

Por qué funciona así

La entrega se trata como una superficie operativa, no como una llamada de disparar y olvidar. Los fallos se clasifican según su intención. Un 4xx distinto de 429 es un rechazo genuino del receptor, por lo que se detiene de inmediato. Un 5xx, un 429 o un error de conexión es transitorio, por lo que gana un reintento con retroceso y tope. Las entregas que agotan todos los intentos nunca se descartan en silencio; caen en una cola de carta muerta inspeccionable que puede reproducirse. La firma liga una marca de tiempo a su cadena base, y cada destino supera una compuerta de egreso, de modo que la autenticidad y la resistencia a la reproducción se cumplen por construcción para cada inquilino.

Contexto de diseño: Operar NextPDF en producción.

Superficie de la API pública

composer require nextpdf/enterprise:^3

Los puntos de integración compatibles son el gestor de webhook (register, unregister, activeRegistrations, dispatch), el objeto de valor de registro (subscribesTo, deactivate), la carga útil (fromJobEvent, toJson, toArray, sign, signedTimestamp), el motor de entrega (deliver, deadLetters, clearDeadLetters), la directiva de reintentos (delayForAttempt, shouldRetry, default, aggressive) y la entrada de carta muerta (markReplayed).

Ejemplo de código — Inicio rápido

use NextPDF\Enterprise\Webhook\WebhookManager;
use NextPDF\Enterprise\Webhook\WebhookRegistration;

$manager->register($tenant, new WebhookRegistration(
    id: $id,
    tenantId: $tenant->tenantId,
    url: 'https://customer.example.com/hooks/nextpdf',
    events: [],            // empty = subscribe to all event types
    secret: $signingSecret,
));

$delivered = $manager->dispatch($tenant, $jobEvent); // count of successes

Verificación en el lado del receptor:

$ts = (int) $request->header('X-NextPDF-Timestamp');
if (abs(time() - $ts) > 300) {
    return new Response(401); // stale timestamp: reject to bound replay
}
$expected = 'sha256=' . hash_hmac('sha256', $ts . '.' . $rawBody, $sharedSecret);
if (! hash_equals($expected, $request->header('X-NextPDF-Signature'))) {
    return new Response(401);
}

Ejemplo de código — Producción

use NextPDF\Enterprise\Webhook\WebhookDelivery;
use NextPDF\Enterprise\Webhook\WebhookRetryPolicy;

$delivery = new WebhookDelivery(
    $httpClient, $requestFactory, $streamFactory,
    retryPolicy: WebhookRetryPolicy::aggressive(), // 10 attempts, 2s base, 10min cap
    logger: $logger,
);

$manager = new WebhookManager($delivery, $logger);
$manager->dispatch($tenant, $jobEvent);

foreach ($delivery->deadLetters() as $dead) {
    $this->scheduleReplay($dead); // inspect last error + last HTTP status
}

Casos límite y trampas

• Una lista de eventos vacía se suscribe a todos. Un registro sin tipos de evento recibe todos los eventos; pase una lista explícita para acotarlo.
• El aislamiento de inquilinos se aplica. Registrarse con un ID de inquilino que difiere del inquilino del contexto se rechaza; el despacho solo itera los registros activos del inquilino que llama.
• 4xx (excepto 429) es terminal. Un 4xx distinto de 429 no se reintenta: se trata como un rechazo permanente del receptor y va a la cola de carta muerta.
• Cancelar el registro es blando. Cancelar el registro desactiva; el registro persiste y se excluye del despacho.
• La cola de carta muerta está en memoria. Es para inspección y reproducción dentro de la vida del proceso; persista las entradas usted mismo si necesita una reproducción duradera entre reinicios.

Rendimiento

El costo del despacho es proporcional al número de registros activos del inquilino que se suscriben al evento. Cada entrega es un HMAC-SHA256 sobre la cadena base firmada más el ciclo de ida y vuelta HTTP; los reintentos añaden retardos de retroceso exponencial acotados. La firma es O(tamaño de la carga útil).

Notas de seguridad

Cada carga útil se autentica con una firma HMAC-SHA256 con la clave del secreto del registro y se envía en la cabecera X-NextPDF-Signature como sha256=<hex>. La firma cubre la cadena base {timestamp}.{body}, y la marca de tiempo viaja en la cabecera X-NextPDF-Timestamp; los receptores verifican con una comparación de tiempo constante y rechazan las entregas fuera de una ventana de frescura para acotar la reproducción. Las URL de destino pasan una compuerta de egreso central antes de cada envío: se exige HTTPS, y los hosts que resuelven a direcciones privadas, de bucle invertido, de enlace local o de metadatos de nube se rechazan sin realizar la solicitud y se encaminan a la cola de carta muerta. El secreto de firma es por registro; trátelo como una credencial. La firma autentica la integridad y el origen de la carga útil; no es una capa de cifrado: no coloque secretos en los datos del evento que el receptor no deba ver.

Conformidad

• La autenticación de la carga útil usa HMAC con SHA-256, el código de autenticación de mensajes con hash con clave de FIPS PUB 198-1; OWASP ASVS 5.0 incluye HMAC-SHA-256 entre sus algoritmos de autenticación de mensajes aprobados.
• Las marcas de tiempo de la carga útil son cadenas de fecha y hora RFC 3339. Nota: RFC 3339 no se ha recuperado del corpus de RAG para esta página; el formato está declarado en código (RFC 3339 extendido) y se marca como declarado en código en lugar de verificado por RAG.

Contrato de comportamiento

• Los registros tienen un alcance estrictamente por inquilino; registrarse bajo un inquilino no coincidente se rechaza y cancelar el registro es una desactivación blanda que preserva el historial.
• Una lista de eventos vacía se suscribe a todos los eventos; solo los registros activos suscritos al tipo de evento reciben un despacho.
• Cada entrega es un HTTP POST con el cuerpo JSON más una cabecera de firma HMAC-SHA256 (sobre la cadena base {timestamp}.{body}), una cabecera de marca de tiempo en segundos unix, el identificador de entrega y el tipo de evento.
• Un 2xx es éxito; un 4xx distinto de 429 es un rechazo permanente (sin reintento); 5xx, 429 o un error de conexión se reintenta hasta el recuento de intentos de la directiva con retroceso de duplicación con tope.
• Los intentos agotados registran la entrega en una cola de carta muerta en memoria (carga útil, recuento de intentos, último error, último estado); una entrada de carta muerta puede marcarse como reproducida.

Frontera de publicación

Esta página documenta únicamente el comportamiento observable desde fuera y la superficie de la API pública compatible. Las rutas internas de espacio de nombres, las clases auxiliares, las tablas de mecanismos, los nombres de archivo de runbook y los prefijos de ticket quedan fuera del alcance.

Alternativa de Core

NextPDF Core (Apache-2.0) no tiene ninguna superficie de registro ni de entrega de webhooks —ninguna—; esta capacidad no tiene equivalente en el nivel Core.

Alternativa de Pro

NextPDF Pro no tiene ninguna superficie de registro ni de entrega de webhooks —ninguna—; esta capacidad no tiene equivalente en el nivel Pro. El gestor de webhook, el registro, la carga útil, el motor de entrega y la directiva de reintentos se incluyen únicamente en el paquete nextpdf/enterprise.

Nota sobre la frontera de Enterprise

La directiva de reintentos, el calendario de retroceso y el manejo de carta muerta se describen a nivel de comportamiento. La cola de carta muerta está en memoria para inspección y reproducción dentro de la vida del proceso; la persistencia duradera entre reinicios y cualquier detalle interno de entrega quedan fuera del alcance de la superficie pública.

Frontera de despliegue

El operador es propietario de los puntos de conexión de devolución de llamada, de los secretos de firma por registro (tratados como credenciales), de la persistencia duradera de las entradas de carta muerta si se requiere la reproducción entre reinicios y de la postura HTTPS de las URL de los receptores. NextPDF Enterprise firma y entrega, pero no persiste por sí mismo los registros ni las cartas muertas más allá de la vida del proceso.

Frontera de cumplimiento legal

No aplica ninguna restricción de control de exportaciones a la superficie de webhook. La firma HMAC autentica la integridad y el origen de la carga útil; no es una capa de cifrado: los operadores no deben colocar secretos en los datos del evento que el receptor no deba ver. Esta documentación no es una opinión legal; consulte a sus propios asesores de cumplimiento y legales.

Véase también

• Webhook — referencia detallada
• SaaS — NextPDF Enterprise
• Metering — NextPDF Enterprise
• Licensing — NextPDF Enterprise