Webhook

W skrócie

NextPDF Enterprise dostarcza zdarzenia zadań do punktów końcowych webhooka dla poszczególnych najemców przez HTTP POST, podpisuje każdy ładunek podpisem HMAC-SHA256, ponawia z wykładniczym wycofaniem i kieruje trwale nieudane dostarczenia do kolejki dead-letter na potrzeby inspekcji i ponownego odtworzenia. Ta strona opisuje obserwowalne zachowanie webhooka oraz kontrakt publiczny.

Dostępność i licencjonowanie

Ta możliwość jest dostarczana w NextPDF Enterprise (nextpdf/enterprise) i aktywuje się wraz z kopertą licencyjną poziomu Enterprise. Wdrożenie bez tego uprawnienia nie ładuje klas tej możliwości. Porównaj edycje i uzyskaj licencję.

Powierzchnia webhooka to podstawowa możliwość Enterprise, dostępna po zainstalowaniu pakietu Enterprise; nie istnieje osobna flaga dla poszczególnych funkcji.

Przegląd koncepcyjny

Najemca rejestruje adres URL wywołania zwrotnego, sekret podpisywania oraz opcjonalną listę typów zdarzeń. Pusta lista zdarzeń oznacza „subskrybuj wszystkie zdarzenia”. Rejestracje są ściśle zawężone do najemcy: najemca może widzieć i zarządzać wyłącznie własnymi rejestracjami, a rejestracja pod niezgodnym najemcą jest odrzucana. Wyrejestrowanie dezaktywuje rejestrację, zamiast ją usuwać, więc historia jest zachowywana; dostarczenia otrzymują wyłącznie aktywne rejestracje.

Gdy zdarzenie zadania jest rozdzielane dla najemcy, każda aktywna rejestracja subskrybująca dany typ zdarzenia otrzymuje dostarczenie. Ładunek to znormalizowany dokument JSON — unikalny identyfikator dostarczenia, identyfikator zadania, typ zdarzenia, dane zdarzenia, znacznik czasu RFC 3339 oraz identyfikator najemcy. Dostarczenie to żądanie HTTP POST niosące treść JSON oraz cztery nagłówki: podpis HMAC-SHA256, znacznik czasu w sekundach uniksowych, identyfikator dostarczenia oraz typ zdarzenia. Podpis jest obliczany nad kanonicznym ciągiem bazowym {timestamp}.{body} z sekretem rejestracji, więc nagłówek znacznika czasu jest kryptograficznie związany z treścią. Odbiorca ponownie oblicza HMAC nad tym samym ciągiem bazowym i odrzuca dostarczenia, których znacznik czasu wykracza poza akceptowalne okno świeżości, co ogranicza powtórzenia (replay).

Dostarczanie korzysta z wykładniczego wycofania. Odpowiedź 2xx to sukces. Odpowiedź 4xx inna niż 429 jest traktowana jako trwałe odrzucenie i nie jest ponawiana. Inne niepowodzenia — 5xx, 429 lub błąd połączenia — są ponawiane do liczby prób z polityki, z podwajającym się opóźnieniem ograniczonym maksimum. Gdy wszystkie próby się wyczerpią, dostarczenie jest rejestrowane w kolejce dead-letter w pamięci z oryginalnym ładunkiem, liczbą prób, ostatnim błędem oraz ostatnim statusem HTTP; wpis dead-letter można oznaczyć jako odtworzony. Dostarczane są dwie polityki ponawiania — default (5 prób, baza 1 s, ograniczenie 5 min) oraz aggressive (10 prób, baza 2 s, ograniczenie 10 min).

Dlaczego działa to w ten sposób

Dostarczanie jest traktowane jako powierzchnia operacyjna, a nie wywołanie typu „wyślij i zapomnij”. Niepowodzenia są klasyfikowane według intencji. 4xx inne niż 429 to prawdziwe odrzucenie przez odbiorcę, więc zatrzymuje się natychmiast. 5xx, 429 lub błąd połączenia jest przejściowy, więc zyskuje ograniczone, wycofujące się ponowienie. Dostarczenia, które wyczerpią wszystkie próby, nigdy nie są cicho porzucane; trafiają do inspekcjonowalnej kolejki dead-letter, którą można odtworzyć. Podpis wiąże znacznik czasu ze swoim ciągiem bazowym, a każdy cel przechodzi przez bramę wyjścia (egress), więc autentyczność i odporność na powtórzenia (replay) są zachowane z konstrukcji dla każdego najemcy.

Tło projektowe: Eksploatacja NextPDF w produkcji.

Powierzchnia publicznego API

composer require nextpdf/enterprise:^3

Obsługiwane punkty integracji to menedżer webhooka (register, unregister, activeRegistrations, dispatch), obiekt wartości rejestracji (subscribesTo, deactivate), ładunek (fromJobEvent, toJson, toArray, sign, signedTimestamp), silnik dostarczania (deliver, deadLetters, clearDeadLetters), polityka ponawiania (delayForAttempt, shouldRetry, default, aggressive) oraz wpis dead-letter (markReplayed).

Przykład kodu — szybki start

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

Weryfikacja po stronie odbiorcy:

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

Przykład kodu — produkcja

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
}

Przypadki brzegowe i pułapki

• Pusta lista zdarzeń subskrybuje wszystko. Rejestracja bez typów zdarzeń otrzymuje każde zdarzenie; przekaż jawną listę, aby ją zawęzić.
• Izolacja najemcy jest egzekwowana. Rejestracja z identyfikatorem najemcy różnym od najemcy z kontekstu jest odrzucana; rozdzielanie iteruje wyłącznie aktywne rejestracje wywołującego najemcy.
• 4xx (z wyjątkiem 429) jest terminalne. 4xx inne niż 429 nie jest ponawiane — jest traktowane jako trwałe odrzucenie przez odbiorcę i trafia do kolejki dead-letter.
• Wyrejestrowanie jest miękkie. Wyrejestrowanie dezaktywuje; rekord pozostaje i jest wykluczony z rozdzielania.
• Kolejka dead-letter jest w pamięci. Służy do inspekcji i ponownego odtworzenia w obrębie czasu życia procesu; utrwalaj wpisy samodzielnie, jeśli potrzebujesz trwałego odtwarzania między restartami.

Wydajność

Koszt rozdzielania jest proporcjonalny do liczby aktywnych rejestracji najemcy subskrybujących zdarzenie. Każde dostarczenie to jeden HMAC-SHA256 nad podpisanym ciągiem bazowym oraz obieg HTTP; ponowienia dodają ograniczone opóźnienia wykładniczego wycofania. Podpisywanie ma złożoność O(rozmiar ładunku).

Uwagi dotyczące bezpieczeństwa

Każdy ładunek jest uwierzytelniany podpisem HMAC-SHA256 kluczowanym sekretem rejestracji i wysyłany w nagłówku X-NextPDF-Signature jako sha256=<hex>. Podpis obejmuje ciąg bazowy {timestamp}.{body}, a znacznik czasu podróżuje w nagłówku X-NextPDF-Timestamp; odbiorcy weryfikują porównaniem w czasie stałym i odrzucają dostarczenia poza oknem świeżości, aby ograniczyć powtórzenia (replay). Docelowe adresy URL przechodzą przez centralną bramę wyjścia (egress) przed każdym wysłaniem: wymagany jest HTTPS, a hosty rozwiązujące się do adresów prywatnych, pętli zwrotnej, link-local lub metadanych chmury są odrzucane bez żądania i kierowane do kolejki dead-letter. Sekret podpisywania jest przypisany do rejestracji; traktuj go jak poświadczenie. Podpis uwierzytelnia integralność i pochodzenie ładunku; nie jest warstwą szyfrowania — nie umieszczaj sekretów w danych zdarzenia, których odbiorca nie powinien widzieć.

Zgodność

• Uwierzytelnianie ładunku korzysta z HMAC z SHA-256, kodu uwierzytelniania wiadomości z kluczowanym skrótem z FIPS PUB 198-1; OWASP ASVS 5.0 wymienia HMAC-SHA-256 wśród zatwierdzonych algorytmów uwierzytelniania wiadomości.
• Znaczniki czasu ładunku to ciągi daty i czasu RFC 3339. Uwaga: RFC 3339 nie zostało pobrane z korpusu RAG dla tej strony; format jest zadeklarowany w kodzie (rozszerzony RFC 3339) i oznaczony jako zadeklarowany w kodzie, a nie zweryfikowany przez RAG.

Kontrakt zachowania

• Rejestracje są ściśle zawężone do najemcy; rejestracja pod niezgodnym najemcą jest odrzucana, a wyrejestrowanie to miękka dezaktywacja zachowująca historię.
• Pusta lista zdarzeń subskrybuje wszystkie zdarzenia; dostarczenie otrzymują wyłącznie aktywne rejestracje subskrybujące dany typ zdarzenia.
• Każde dostarczenie to żądanie HTTP POST z treścią JSON oraz nagłówkiem podpisu HMAC-SHA256 (nad ciągiem bazowym {timestamp}.{body}), nagłówkiem znacznika czasu w sekundach uniksowych, identyfikatorem dostarczenia oraz typem zdarzenia.
• 2xx to sukces; 4xx inne niż 429 to trwałe odrzucenie (bez ponawiania); 5xx, 429 lub błąd połączenia jest ponawiane do liczby prób z polityki z ograniczonym podwajającym się wycofaniem.
• Wyczerpane próby rejestrują dostarczenie w kolejce dead-letter w pamięci (ładunek, liczba prób, ostatni błąd, ostatni status); wpis dead-letter można oznaczyć jako odtworzony.

Granica publikacji

Ta strona dokumentuje wyłącznie zewnętrznie obserwowalne zachowanie oraz obsługiwaną powierzchnię publicznego API. Wewnętrzne ścieżki przestrzeni nazw, klasy pomocnicze, tabele mechanizmów, nazwy plików runbooków oraz prefiksy zgłoszeń są poza zakresem.

Rozwiązanie zastępcze Core

NextPDF Core (Apache-2.0) nie ma powierzchni rejestracji ani dostarczania webhooków — żadnej; ta możliwość nie ma odpowiednika na poziomie Core.

Rozwiązanie zastępcze Pro

NextPDF Pro nie ma powierzchni rejestracji ani dostarczania webhooków — żadnej; ta możliwość nie ma odpowiednika na poziomie Pro. Menedżer webhooka, rejestracja, ładunek, silnik dostarczania oraz polityka ponawiania są dostarczane wyłącznie w pakiecie nextpdf/enterprise.

Uwaga o granicy Enterprise

Polityka ponawiania, harmonogram wycofania oraz obsługa dead-letter są opisane na poziomie zachowania. Kolejka dead-letter jest w pamięci na potrzeby inspekcji i ponownego odtworzenia w obrębie czasu życia procesu; trwałe utrwalanie między restartami oraz wszelkie wewnętrzne mechanizmy dostarczania są poza zakresem powierzchni publicznej.

Granica wdrożenia

Operator odpowiada za punkty końcowe wywołania zwrotnego, sekrety podpisywania dla poszczególnych rejestracji (traktowane jako poświadczenia), trwałe utrwalanie wpisów dead-letter, jeśli wymagane jest odtwarzanie między restartami, oraz postawę HTTPS adresów URL odbiorcy. NextPDF Enterprise podpisuje i dostarcza, lecz sam nie utrwala rejestracji ani wpisów dead-letter poza czasem życia procesu.

Granica zgodności prawnej

Do powierzchni webhooka nie ma zastosowania żadne ograniczenie kontroli eksportu. Podpis HMAC uwierzytelnia integralność i pochodzenie ładunku; nie jest warstwą szyfrowania — operatorzy nie mogą umieszczać sekretów w danych zdarzenia, których odbiorca nie powinien widzieć. Ta dokumentacja nie jest opinią prawną; skonsultuj się z własnymi doradcami ds. zgodności i prawnymi.

Zobacz też

• Webhook — pełna referencja
• SaaS — NextPDF Enterprise
• Metering — NextPDF Enterprise
• Licensing — NextPDF Enterprise