Enterprise Edition

Webhook

Auf einen Blick

NextPDF Enterprise liefert Job-Ereignisse über HTTP-POST an Webhook-Endpunkte pro Mandant aus, signiert jeden Payload mit einer HMAC-SHA256-Signatur, versucht mit exponentiellem Backoff erneut und routet dauerhaft fehlgeschlagene Auslieferungen zur Inspektion und zum Replay in eine Dead-Letter-Queue. Diese Seite beschreibt das beobachtbare Webhook-Verhalten und den öffentlichen Vertrag.

Verfügbarkeit & Lizenzierung

Diese Fähigkeit wird in NextPDF Enterprise (nextpdf/enterprise) ausgeliefert und aktiviert sich mit einem Lizenz-Envelope der Enterprise-Stufe. Eine Bereitstellung ohne diese Berechtigung lädt die Klassen der Fähigkeit nicht. Editionen vergleichen und Lizenz erwerben.

Die Webhook-Oberfläche ist eine Basis-Enterprise-Fähigkeit, die verfügbar ist, sobald das Enterprise-Paket installiert ist; es gibt kein separates Flag pro Funktion.

Konzeptioneller Überblick

Ein Mandant registriert eine Callback-URL, ein Signier-Secret und eine optionale Liste von Ereignistypen. Eine leere Ereignisliste bedeutet „alle Ereignisse abonnieren“. Registrierungen sind strikt mandantengescopt: Ein Mandant kann nur seine eigenen Registrierungen sehen und verwalten, und das Registrieren unter einem nicht passenden Mandanten wird abgelehnt. Das Abmelden deaktiviert die Registrierung, statt sie zu löschen, sodass die Historie bewahrt wird; nur aktive Registrierungen erhalten Dispatches.

Wenn ein Job-Ereignis für einen Mandanten dispatcht wird, erhält jede aktive Registrierung, die den Ereignistyp abonniert, eine Auslieferung. Der Payload ist ein standardisiertes JSON-Dokument — eine eindeutige Auslieferungskennung, die Job-Kennung, der Ereignistyp, die Ereignisdaten, ein RFC 3339-Zeitstempel und die Mandantenkennung. Die Auslieferung ist ein HTTP-POST, der den JSON-Body und vier Header trägt: eine HMAC-SHA256-Signatur, einen Zeitstempel in Unix-Sekunden, die Auslieferungskennung und den Ereignistyp. Die Signatur wird über den kanonischen Basis-String {timestamp}.{body} mit dem Secret der Registrierung berechnet, sodass der Zeitstempel-Header kryptografisch an den Body gebunden ist. Der Empfänger berechnet den HMAC über denselben Basis-String neu und lehnt Auslieferungen ab, deren Zeitstempel außerhalb eines akzeptablen Aktualitätsfensters liegt, was Replays begrenzt.

Die Auslieferung verwendet exponentiellen Backoff. Eine 2xx-Antwort ist Erfolg. Eine 4xx-Antwort außer 429 wird als dauerhafte Ablehnung behandelt und nicht erneut versucht. Andere Fehler — 5xx, 429 oder ein Verbindungsfehler — werden bis zur Versuchszahl der Richtlinie mit einer sich verdoppelnden, auf ein Maximum gedeckelten Verzögerung erneut versucht. Wenn alle Versuche erschöpft sind, wird die Auslieferung in einer In-Memory-Dead-Letter-Queue mit dem ursprünglichen Payload, der Versuchszahl, dem letzten Fehler und dem letzten HTTP-Status erfasst; ein Dead-Letter-Eintrag kann als replayed markiert werden. Zwei Retry-Richtlinien werden ausgeliefert — eine default (5 Versuche, 1s Basis, 5min Deckel) und eine aggressive (10 Versuche, 2s Basis, 10min Deckel).

Warum es so funktioniert

Die Auslieferung wird als betriebliche Oberfläche behandelt, nicht als Fire-and-forget-Aufruf. Fehler werden nach Intention klassifiziert. Ein 4xx außer 429 ist eine echte Empfängerablehnung und stoppt daher sofort. Ein 5xx, ein 429 oder ein Verbindungsfehler ist transient und verdient daher einen gedeckelten, zurückweichenden Retry. Auslieferungen, die jeden Versuch erschöpfen, werden niemals stillschweigend verworfen; sie landen in einer inspizierbaren Dead-Letter-Queue, die erneut abgespielt werden kann. Die Signatur bindet einen Zeitstempel in ihren Basis-String ein, und jedes Ziel durchläuft ein Egress-Gate, sodass Authentizität und Replay-Resistenz für jeden Mandanten konstruktionsbedingt gelten.

Design-Hintergrund: NextPDF in der Produktion betreiben.

Öffentliche API-Oberfläche

composer require nextpdf/enterprise:^3

Die unterstützten Integrationspunkte sind der Webhook-Manager (register, unregister, activeRegistrations, dispatch), das Registrierungs-Value-Object (subscribesTo, deactivate), der Payload (fromJobEvent, toJson, toArray, sign, signedTimestamp), die Auslieferungs-Engine (deliver, deadLetters, clearDeadLetters), die Retry-Richtlinie (delayForAttempt, shouldRetry, default, aggressive) und der Dead-Letter-Eintrag (markReplayed).

Codebeispiel — Schnellstart

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

Verifikation auf Empfängerseite:

$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);
}

Codebeispiel — Produktion

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
}

Sonderfälle & Fallstricke

Leere Ereignisliste abonniert alle. Eine Registrierung ohne Ereignistypen erhält jedes Ereignis; übergeben Sie eine explizite Liste, um sie zu scopen.
Mandantenisolierung wird durchgesetzt. Das Registrieren mit einer Mandanten-ID, die von der Kontext-Mandanten-ID abweicht, wird abgelehnt; der Dispatch iteriert nur über die aktiven Registrierungen des aufrufenden Mandanten.
4xx (außer 429) ist terminal. Ein 4xx außer 429 wird nicht erneut versucht — es wird als dauerhafte Empfängerablehnung behandelt und geht in die Dead-Letter-Queue.
Abmelden ist soft. Das Abmelden deaktiviert; der Datensatz bleibt bestehen und wird vom Dispatch ausgeschlossen.
Dead-Letter-Queue ist In-Memory. Sie dient der Inspektion und dem Replay innerhalb der Prozesslebensdauer; persistieren Sie Einträge selbst, wenn Sie dauerhaftes Replay über Neustarts hinweg benötigen.

Performance

Die Dispatch-Kosten sind proportional zur Anzahl der aktiven Registrierungen des Mandanten, die das Ereignis abonnieren. Jede Auslieferung ist ein HMAC-SHA256 über den signierten Basis-String plus der HTTP-Roundtrip; Retries fügen begrenzte exponentielle Backoff-Verzögerungen hinzu. Das Signieren ist O(Payload-Größe).

Sicherheitshinweise

Jeder Payload wird mit einer HMAC-SHA256-Signatur authentifiziert, die mit dem Secret der Registrierung als Schlüssel verarbeitet und im Header X-NextPDF-Signature als sha256=<hex> gesendet wird. Die Signatur deckt den Basis-String {timestamp}.{body} ab, und der Zeitstempel wird im Header X-NextPDF-Timestamp übertragen; Empfänger verifizieren mit einem Konstant-Zeit-Vergleich und lehnen Auslieferungen außerhalb eines Aktualitätsfensters ab, um Replays zu begrenzen. Ziel-URLs durchlaufen vor jedem Senden ein zentrales Egress-Gate: HTTPS ist erforderlich, und Hosts, die zu privaten, Loopback-, Link-local- oder Cloud-Metadaten-Adressen auflösen, werden ohne Anfrage abgewiesen und in die Dead-Letter-Queue geroutet. Das Signier-Secret ist pro Registrierung; behandeln Sie es als Anmeldedatum. Die Signatur authentifiziert die Payload-Integrität und -Herkunft; sie ist keine Verschlüsselungsschicht — legen Sie keine Secrets in Ereignisdaten ab, die der Empfänger nicht sehen soll.

Konformität

Die Payload-Authentifizierung verwendet HMAC mit SHA-256, den keyed-Hash-Message-Authentication-Code von FIPS PUB 198-1; OWASP ASVS 5.0 führt HMAC-SHA-256 unter seinen zugelassenen Message-Authentication-Algorithmen auf.
Payload-Zeitstempel sind RFC 3339-Datum-Zeit-Strings. Hinweis: RFC 3339 wurde für diese Seite nicht aus dem RAG-Korpus abgerufen; das Format ist code-deklariert (RFC 3339 erweitert) und als code-deklariert statt RAG-verifiziert markiert.

Verhaltensvertrag

Registrierungen sind strikt mandantengescopt; das Registrieren unter einem nicht passenden Mandanten wird abgelehnt, und das Abmelden ist ein Soft-Deactivate, das die Historie bewahrt.
Eine leere Ereignisliste abonniert alle Ereignisse; nur aktive Registrierungen, die den Ereignistyp abonnieren, erhalten einen Dispatch.
Jede Auslieferung ist ein HTTP-POST mit dem JSON-Body plus einem HMAC-SHA256-Signatur-Header (über den Basis-String {timestamp}.{body}), einem Zeitstempel-Header in Unix-Sekunden, der Auslieferungskennung und dem Ereignistyp.
Ein 2xx ist Erfolg; ein 4xx außer 429 ist eine dauerhafte Ablehnung (kein Retry); 5xx, 429 oder ein Verbindungsfehler wird bis zur Versuchszahl der Richtlinie mit gedeckeltem, sich verdoppelndem Backoff erneut versucht.
Erschöpfte Versuche erfassen die Auslieferung in einer In-Memory-Dead-Letter-Queue (Payload, Versuchszahl, letzter Fehler, letzter Status); ein Dead-Letter-Eintrag kann als replayed markiert werden.

Publikationsgrenze

Diese Seite dokumentiert ausschließlich extern beobachtbares Verhalten und die unterstützte öffentliche API-Oberfläche. Interne Namespace-Pfade, Hilfsklassen, Mechanismus-Tabellen, Runbook-Dateinamen und Ticket-Präfixe liegen außerhalb des Umfangs.

Core-Fallback

NextPDF Core (Apache-2.0) hat keine Webhook-Registrierungs- oder Auslieferungsoberfläche — keine; diese Fähigkeit hat kein Core-Tier-Äquivalent.

Pro-Fallback

NextPDF Pro hat keine Webhook-Registrierungs- oder Auslieferungsoberfläche — keine; diese Fähigkeit hat kein Pro-Tier-Äquivalent. Der Webhook-Manager, die Registrierung, der Payload, die Auslieferungs-Engine und die Retry-Richtlinie werden ausschließlich im Paket nextpdf/enterprise ausgeliefert.

Hinweis zur Enterprise-Grenze

Die Retry-Richtlinie, der Backoff-Zeitplan und die Dead-Letter-Behandlung werden auf Verhaltensebene beschrieben. Die Dead-Letter-Queue ist In-Memory zur Inspektion und zum Replay innerhalb der Prozesslebensdauer; die dauerhafte Persistenz über Neustarts hinweg und jegliche internen Auslieferungs-Interna liegen außerhalb des Umfangs der öffentlichen Oberfläche.

Deployment-Grenze

Der Betreiber besitzt die Callback-Endpunkte, die Signier-Secrets pro Registrierung (als Anmeldedaten behandelt), die dauerhafte Persistenz von Dead-Letter-Einträgen, falls ein Replay über Neustarts hinweg erforderlich ist, und die HTTPS-Haltung der Empfänger-URLs. NextPDF Enterprise signiert und liefert aus, persistiert aber selbst weder Registrierungen noch Dead Letters über die Prozesslebensdauer hinaus.

Grenze der rechtlichen Compliance

Auf die Webhook-Oberfläche gilt keine exportkontrollrechtliche Einschränkung. Die HMAC-Signatur authentifiziert die Payload-Integrität und -Herkunft; sie ist keine Verschlüsselungsschicht — Betreiber dürfen keine Secrets in Ereignisdaten ablegen, die der Empfänger nicht sehen soll. Diese Dokumentation ist kein Rechtsgutachten; konsultieren Sie Ihre eigenen Compliance- und Rechtsberater.