Enterprise редакция

Webhook

Кратко

NextPDF Enterprise доставляет события задач на конечные точки веб-перехватчиков для каждого арендатора по HTTP POST, подписывает каждую полезную нагрузку подписью HMAC-SHA256, повторяет попытки с экспоненциальной отсрочкой и направляет окончательно сбойные доставки в очередь недоставленных сообщений для проверки и повтора. Эта страница описывает наблюдаемое поведение веб-перехватчиков и публичный контракт.

Доступность и лицензирование

Эта возможность поставляется в NextPDF Enterprise (nextpdf/enterprise) и активируется лицензионным конвертом уровня Enterprise. Развёртывание без этого права не загружает классы возможности. Сравните редакции и получите лицензию.

Поверхность веб-перехватчиков — это базовая возможность Enterprise, доступная после установки пакета Enterprise; отдельного флага для каждой функции нет.

Концептуальный обзор

Арендатор регистрирует URL обратного вызова, секрет подписания и необязательный список типов событий. Пустой список событий означает «подписаться на все события». Регистрации строго ограничены областью арендатора: арендатор может видеть и управлять только своими регистрациями, а регистрация под несовпадающим арендатором отклоняется. Отмена регистрации деактивирует регистрацию, а не удаляет её, поэтому история сохраняется; только активные регистрации получают доставки.

Когда событие задачи отправляется для арендатора, каждая активная регистрация, подписанная на тип события, получает доставку. Полезная нагрузка — это стандартизированный документ JSON: уникальный идентификатор доставки, идентификатор задачи, тип события, данные события, временная метка RFC 3339 и идентификатор арендатора. Доставка — это HTTP POST, несущий тело JSON и четыре заголовка: подпись HMAC-SHA256, временную метку в секундах Unix, идентификатор доставки и тип события. Подпись вычисляется по канонической базовой строке {timestamp}.{body} с секретом регистрации, поэтому заголовок временной метки криптографически связан с телом. Получатель пересчитывает HMAC по той же базовой строке и отклоняет доставки, чья временная метка выходит за приемлемое окно свежести, что ограничивает повторное воспроизведение.

Доставка использует экспоненциальную отсрочку. Ответ 2xx — это успех. Ответ 4xx, кроме 429, рассматривается как окончательное отклонение и не повторяется. Другие сбои — 5xx, 429 или ошибка соединения — повторяются вплоть до числа попыток политики с удваивающейся задержкой, ограниченной максимумом. Когда все попытки исчерпаны, доставка записывается в очередь недоставленных сообщений в памяти с исходной полезной нагрузкой, числом попыток, последней ошибкой и последним статусом HTTP; запись недоставленных сообщений можно пометить как повторённую. Поставляются две политики повторов — default (5 попыток, база 1 с, потолок 5 мин) и aggressive (10 попыток, база 2 с, потолок 10 мин).

Почему это работает именно так

Доставка рассматривается как операционная поверхность, а не вызов «отправил и забыл». Сбои классифицируются по намерению. 4xx, кроме 429, — это подлинное отклонение получателем, поэтому оно останавливается сразу. 5xx, 429 или ошибка соединения — это временный сбой, поэтому он заслуживает ограниченного повтора с отсрочкой. Доставки, исчерпавшие все попытки, никогда не отбрасываются молча; они попадают в проверяемую очередь недоставленных сообщений, которую можно воспроизвести повторно. Подпись связывает временную метку в свою базовую строку, а каждый пункт назначения проходит шлюз исходящего трафика, поэтому аутентичность и устойчивость к повторному воспроизведению обеспечиваются по построению для каждого арендатора.

Проектный контекст: Эксплуатация NextPDF в продакшене.

Поверхность публичного API

composer require nextpdf/enterprise:^3

Поддерживаемые точки интеграции — это менеджер веб-перехватчиков (register, unregister, activeRegistrations, dispatch), объект-значение регистрации (subscribesTo, deactivate), полезная нагрузка (fromJobEvent, toJson, toArray, sign, signedTimestamp), движок доставки (deliver, deadLetters, clearDeadLetters), политика повторов (delayForAttempt, shouldRetry, default, aggressive) и запись недоставленных сообщений (markReplayed).

Пример кода — быстрый старт

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

Проверка на стороне получателя:

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

Пример кода — продакшен

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
}

Граничные случаи и подводные камни

Пустой список событий подписывает на всё. Регистрация без типов событий получает каждое событие; передайте явный список, чтобы ограничить её.
Изоляция арендаторов обеспечивается. Регистрация с идентификатором арендатора, отличным от арендатора контекста, отклоняется; диспетчеризация перебирает только активные регистрации вызывающего арендатора.
4xx (кроме 429) является окончательным. 4xx, кроме 429, не повторяется — он рассматривается как окончательное отклонение получателем и идёт в очередь недоставленных сообщений.
Отмена регистрации мягкая. Отмена регистрации деактивирует; запись сохраняется и исключается из диспетчеризации.
Очередь недоставленных сообщений в памяти. Она предназначена для проверки и повтора в течение времени жизни процесса; сохраняйте записи сами, если вам нужен устойчивый повтор после перезапусков.

Производительность

Стоимость диспетчеризации пропорциональна числу активных регистраций арендатора, подписанных на событие. Каждая доставка — это один HMAC-SHA256 по подписанной базовой строке плюс цикл обмена HTTP; повторы добавляют ограниченные задержки экспоненциальной отсрочки. Подписание — O(размер полезной нагрузки).

Замечания по безопасности

Каждая полезная нагрузка аутентифицируется подписью HMAC-SHA256 с ключом — секретом регистрации — и отправляется в заголовке X-NextPDF-Signature как sha256=<hex>. Подпись покрывает базовую строку {timestamp}.{body}, а временная метка передаётся в заголовке X-NextPDF-Timestamp; получатели проверяют её сравнением за постоянное время и отклоняют доставки за пределами окна свежести, чтобы ограничить повторное воспроизведение. URL пунктов назначения проходят центральный шлюз исходящего трафика перед каждой отправкой: HTTPS обязателен, а хосты, разрешающиеся в частные, петлевые, локально-канальные адреса или адреса облачных метаданных, отклоняются без запроса и направляются в очередь недоставленных сообщений. Секрет подписания — для каждой регистрации; относитесь к нему как к учётным данным. Подпись аутентифицирует целостность и происхождение полезной нагрузки; это не слой шифрования — не помещайте секреты в данные события, которые получатель не должен видеть.

Соответствие

Аутентификация полезной нагрузки использует HMAC с SHA-256, код аутентификации сообщений с ключом из FIPS PUB 198-1; OWASP ASVS 5.0 включает HMAC-SHA-256 в число своих одобренных алгоритмов аутентификации сообщений.
Временные метки полезной нагрузки — это строки даты-времени RFC 3339. Примечание: RFC 3339 не извлекался из корпуса RAG для этой страницы; формат объявлен в коде (расширенный RFC 3339) и помечен как объявленный в коде, а не подтверждённый по RAG.

Контракт поведения

Регистрации строго ограничены областью арендатора; регистрация под несовпадающим арендатором отклоняется, а отмена регистрации — это мягкая деактивация, сохраняющая историю.
Пустой список событий подписывает на все события; только активные регистрации, подписанные на тип события, получают доставку.
Каждая доставка — это HTTP POST с телом JSON плюс заголовок подписи HMAC-SHA256 (по базовой строке {timestamp}.{body}), заголовок временной метки в секундах Unix, идентификатор доставки и тип события.
2xx — это успех; 4xx, кроме 429, — окончательное отклонение (без повтора); 5xx, 429 или ошибка соединения повторяется вплоть до числа попыток политики с ограниченной удваивающейся отсрочкой.
Исчерпанные попытки записывают доставку в очередь недоставленных сообщений в памяти (полезная нагрузка, число попыток, последняя ошибка, последний статус); запись недоставленных сообщений можно пометить как повторённую.

Граница публикации

Эта страница документирует только внешне наблюдаемое поведение и поддерживаемую поверхность публичного API. Внутренние пути пространств имён, вспомогательные классы, таблицы механизмов, имена файлов runbook и префиксы тикетов выходят за рамки.

Резервный вариант Core

У NextPDF Core (Apache-2.0) нет поверхности регистрации или доставки веб-перехватчиков — никакой; у этой возможности нет эквивалента в уровне Core.

Резервный вариант Pro

У NextPDF Pro нет поверхности регистрации или доставки веб-перехватчиков — никакой; у этой возможности нет эквивалента в уровне Pro. Менеджер веб-перехватчиков, регистрация, полезная нагрузка, движок доставки и политика повторов поставляются только в пакете nextpdf/enterprise.

Примечание о границе Enterprise

Политика повторов, расписание отсрочки и обработка недоставленных сообщений описаны на уровне поведения. Очередь недоставленных сообщений в памяти предназначена для проверки и повтора в течение времени жизни процесса; устойчивое хранение между перезапусками и любые внутренние детали доставки выходят за рамки публичной поверхности.

Граница развёртывания

Оператор владеет конечными точками обратного вызова, секретами подписания для каждой регистрации (рассматриваемыми как учётные данные), устойчивым хранением записей недоставленных сообщений, если требуется повтор после перезапуска, и положением URL получателей в части HTTPS. NextPDF Enterprise подписывает и доставляет, но сам не сохраняет регистрации или недоставленные сообщения за пределами времени жизни процесса.

Граница юридического соответствия

К поверхности веб-перехватчиков не применяется ограничение экспортного контроля. Подпись HMAC аутентифицирует целостность и происхождение полезной нагрузки; это не слой шифрования — операторы не должны помещать секреты в данные события, которые получатель не должен видеть. Эта документация не является юридическим заключением; обращайтесь к собственным консультантам по комплаенсу и праву.