Enterprise editie

Webhook

In het kort

NextPDF Enterprise levert taakgebeurtenissen af aan per-tenant webhook-endpoints over HTTP POST, ondertekent elke payload met een HMAC-SHA256-handtekening, probeert opnieuw met exponentiële backoff en routeert permanent gefaalde afleveringen naar een dead-letter-wachtrij voor inspectie en replay. Deze pagina beschrijft het waarneembare webhook-gedrag en het publieke contract.

Beschikbaarheid en licentie

Deze mogelijkheid wordt geleverd in NextPDF Enterprise (nextpdf/enterprise) en activeert met een licentie-envelop van het Enterprise-niveau. Een deployment zonder dat recht laadt de klassen van de mogelijkheid niet. Vergelijk edities en verkrijg een licentie.

Het webhook-oppervlak is een basismogelijkheid van Enterprise, beschikbaar zodra het Enterprise-pakket is geïnstalleerd; er is geen aparte vlag per functie.

Conceptueel overzicht

Een tenant registreert een callback-URL, een ondertekeningsgeheim en een optionele lijst van gebeurtenistypen. Een lege gebeurtenissenlijst betekent “abonneer op alle gebeurtenissen”. Registraties zijn strikt tenant-gescoped: een tenant kan alleen zijn eigen registraties zien en beheren, en registreren onder een niet-overeenkomende tenant wordt afgewezen. Uitschrijven deactiveert de registratie in plaats van die te verwijderen, zodat historie behouden blijft; alleen actieve registraties ontvangen dispatches.

Wanneer een taakgebeurtenis voor een tenant wordt verzonden, ontvangt elke actieve registratie die zich op het gebeurtenistype abonneert een aflevering. De payload is een gestandaardiseerd JSON-document — een unieke afleveringsidentificator, de taakidentificator, het gebeurtenistype, de gebeurtenisgegevens, een RFC 3339-tijdstempel en de tenant-identificator. De aflevering is een HTTP POST die de JSON-body en vier headers draagt: een HMAC-SHA256-handtekening, een tijdstempel in unix-seconden, de afleveringsidentificator en het gebeurtenistype. De handtekening wordt berekend over de canonieke basisstring {timestamp}.{body} met het geheim van de registratie, zodat de tijdstempel-header cryptografisch aan de body wordt gebonden. De ontvanger herberekent de HMAC over dezelfde basisstring en wijst afleveringen af waarvan de tijdstempel buiten een aanvaardbaar versheidsvenster valt, wat replay begrenst.

Aflevering gebruikt exponentiële backoff. Een 2xx-respons is succes. Een 4xx-respons anders dan 429 wordt behandeld als een permanente afwijzing en wordt niet opnieuw geprobeerd. Andere fouten — 5xx, 429 of een verbindingsfout — worden opnieuw geprobeerd tot het aantal pogingen van het beleid met een verdubbelende vertraging begrensd op een maximum. Wanneer alle pogingen zijn uitgeput, wordt de aflevering vastgelegd in een in-memory dead-letter-wachtrij met de originele payload, het aantal pogingen, de laatste fout en de laatste HTTP-status; een dead-letter-vermelding kan als replayed worden gemarkeerd. Er worden twee retry policies geleverd — een default (5 pogingen, 1s basis, 5min cap) en een aggressive (10 pogingen, 2s basis, 10min cap).

Waarom het zo werkt

Aflevering wordt behandeld als een operationeel oppervlak, niet als een fire-and-forget-aanroep. Fouten worden geclassificeerd naar intentie. Een 4xx anders dan 429 is een echte ontvangerafwijzing en stopt dus meteen. Een 5xx, een 429 of een verbindingsfout is transient en verdient dus een begrensde, backing-off retry. Afleveringen die elke poging uitputten worden nooit stilzwijgend weggegooid; ze belanden in een inspecteerbare dead-letter-wachtrij die kan worden replayed. De handtekening bindt een tijdstempel in zijn basisstring, en elke bestemming passeert een egress-gate, zodat authenticiteit en replay-weerstand per tenant per constructie gelden.

Ontwerpachtergrond: NextPDF in productie draaien.

Publiek API-oppervlak

composer require nextpdf/enterprise:^3

De ondersteunde integratiepunten zijn de webhook manager (register, unregister, activeRegistrations, dispatch), het registratie-value-object (subscribesTo, deactivate), de payload (fromJobEvent, toJson, toArray, sign, signedTimestamp), de delivery engine (deliver, deadLetters, clearDeadLetters), de retry policy (delayForAttempt, shouldRetry, default, aggressive) en de dead-letter-vermelding (markReplayed).

Codevoorbeeld — snelstart

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

Verificatie aan de ontvangerszijde:

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

Codevoorbeeld — productie

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
}

Randgevallen en valkuilen

Lege gebeurtenissenlijst abonneert op alle. Een registratie zonder gebeurtenistypen ontvangt elke gebeurtenis; geef een expliciete lijst door om die te scopen.
Tenant-isolatie wordt afgedwongen. Registreren met een tenant-ID die verschilt van de context-tenant wordt afgewezen; dispatch itereert alleen over de actieve registraties van de aanroepende tenant.
4xx (behalve 429) is terminaal. Een 4xx anders dan 429 wordt niet opnieuw geprobeerd — het wordt behandeld als een permanente ontvangerafwijzing en gaat naar de dead-letter-wachtrij.
Uitschrijven is soft. Uitschrijven deactiveert; de record persisteert en wordt uitgesloten van dispatch.
Dead-letter-wachtrij is in-memory. Ze is voor inspectie en replay binnen de levensduur van het proces; persisteer vermeldingen zelf als je duurzame replay over herstarts heen nodig hebt.

Prestaties

De dispatch-kosten zijn evenredig aan het aantal actieve registraties voor de tenant die zich op de gebeurtenis abonneren. Elke aflevering is één HMAC-SHA256 over de ondertekende basisstring plus de HTTP-round-trip; retries voegen begrensde exponentiële-backoff-vertragingen toe. Ondertekening is O(payloadgrootte).

Beveiligingsnotities

Elke payload wordt geauthenticeerd met een HMAC-SHA256-handtekening gekeyd met het geheim van de registratie en verzonden in de X-NextPDF-Signature-header als sha256=<hex>. De handtekening dekt de basisstring {timestamp}.{body}, en de tijdstempel reist in de X-NextPDF-Timestamp-header; ontvangers verifiëren met een constante-tijdvergelijking en wijzen afleveringen buiten een versheidsvenster af om replay te begrenzen. Bestemmings-URL’s passeren een centrale egress-gate vóór elke verzending: HTTPS is vereist, en hosts die resolven naar private, loopback, link-local of cloud-metadata-adressen worden zonder verzoek geweigerd en naar de dead-letter-wachtrij gerouteerd. Het ondertekeningsgeheim is per registratie; behandel het als een referentie. De handtekening authenticeert payload-integriteit en herkomst; het is geen encryptielaag — plaats geen geheimen in gebeurtenisgegevens die de ontvanger niet zou mogen zien.

Conformiteit

Payload-authenticatie gebruikt HMAC met SHA-256, de keyed-hash message authentication code van FIPS PUB 198-1; OWASP ASVS 5.0 vermeldt HMAC-SHA-256 onder zijn goedgekeurde message-authentication-algoritmen.
Payload-tijdstempels zijn RFC 3339-date-time-strings. Opmerking: RFC 3339 is voor deze pagina niet uit het RAG-corpus opgehaald; het formaat is code-declared (RFC 3339 extended) en gemarkeerd als code-declared in plaats van RAG-verified.

Gedragscontract

Registraties zijn strikt tenant-gescoped; registreren onder een niet-overeenkomende tenant wordt afgewezen en uitschrijven is een soft deactivate die historie behoudt.
Een lege gebeurtenissenlijst abonneert op alle gebeurtenissen; alleen actieve registraties die zich op het gebeurtenistype abonneren ontvangen een dispatch.
Elke aflevering is een HTTP POST met de JSON-body plus een HMAC-SHA256-handtekeningheader (over de basisstring {timestamp}.{body}), een tijdstempel-header in unix-seconden, de afleveringsidentificator en het gebeurtenistype.
Een 2xx is succes; een 4xx anders dan 429 is een permanente afwijzing (geen retry); 5xx, 429 of een verbindingsfout wordt opnieuw geprobeerd tot het aantal pogingen van het beleid met begrensde verdubbelende backoff.
Uitgeputte pogingen leggen de aflevering vast in een in-memory dead-letter-wachtrij (payload, aantal pogingen, laatste fout, laatste status); een dead-letter-vermelding kan als replayed worden gemarkeerd.

Publicatiegrens

Deze pagina documenteert alleen extern waarneembaar gedrag en het ondersteunde publieke API-oppervlak. Interne namespace-paden, helper-klassen, mechanismetabellen, runbook-bestandsnamen en ticketprefixen vallen buiten de scope.

Core-terugval

NextPDF Core (Apache-2.0) heeft geen webhook-registratie- of afleveringsoppervlak — geen; deze mogelijkheid heeft geen equivalent op Core-niveau.

Pro-terugval

NextPDF Pro heeft geen webhook-registratie- of afleveringsoppervlak — geen; deze mogelijkheid heeft geen equivalent op Pro-niveau. De webhook manager, registratie, payload, delivery engine en retry policy worden alleen geleverd in het nextpdf/enterprise-pakket.

Opmerking over de Enterprise-grens

De retry policy, het backoff-schema en de dead-letter-afhandeling worden op gedragsniveau beschreven. De dead-letter-wachtrij is in-memory voor inspectie en replay binnen de levensduur van het proces; duurzame cross-restart-persistentie en eventuele interne delivery-internals vallen buiten de scope van het openbare oppervlak.

Implementatiegrens

De operator is eigenaar van de callback-endpoints, de ondertekeningsgeheimen per registratie (behandeld als referenties), de duurzame persistentie van dead-letter-vermeldingen als cross-restart-replay vereist is, en de HTTPS-positie van ontvanger-URL’s. NextPDF Enterprise ondertekent en levert af maar persisteert zelf geen registraties of dead letters buiten de levensduur van het proces.

Juridische-compliancegrens

Er geldt geen exportcontrolebeperking voor het webhook-oppervlak. De HMAC-handtekening authenticeert payload-integriteit en herkomst; het is geen encryptielaag — operators mogen geen geheimen plaatsen in gebeurtenisgegevens die de ontvanger niet zou mogen zien. Deze documentatie is geen juridisch oordeel; raadpleeg je eigen compliance- en juridische adviseurs.