Enterprise 에디션

Webhook

한눈에 보기

NextPDF Enterprise는 작업 이벤트를 HTTP POST를 통해 테넌트별 웹훅 엔드포인트로 전달하고, 각 페이로드를 HMAC-SHA256 서명으로 서명하며, 지수 백오프로 재시도하고, 영구적으로 실패한 전달을 검사 및 재생을 위한 데드 레터(dead-letter) 큐로 라우팅합니다. 이 페이지는 관찰 가능한 웹훅 동작과 공개 계약을 설명합니다.

가용성 및 라이선싱

이 역량은 NextPDF Enterprise(nextpdf/enterprise)에 포함되어 있으며 Enterprise 등급 라이선스 봉투로 활성화됩니다. 해당 자격이 없는 배포는 이 역량의 클래스를 로드하지 않습니다. 에디션 비교 및 라이선스 받기.

웹훅 표면은 기본 Enterprise 역량으로, Enterprise 패키지가 설치되면 사용할 수 있습니다. 별도의 기능별 플래그는 없습니다.

개념 개요

테넌트는 콜백 URL, 서명 시크릿, 그리고 선택적 이벤트 유형 목록을 등록합니다. 이벤트 목록이 비어 있으면 “모든 이벤트 구독”을 의미합니다. 등록은 엄격하게 테넌트 스코프입니다. 즉, 테넌트는 자신의 등록만 보고 관리할 수 있으며, 일치하지 않는 테넌트로 등록하는 것은 거부됩니다. 등록 해제는 등록을 삭제하는 대신 비활성화하므로 이력이 보존됩니다. 활성 등록만 디스패치를 받습니다.

작업 이벤트가 한 테넌트에 대해 디스패치되면, 그 이벤트 유형을 구독하는 각 활성 등록이 전달을 받습니다. 페이로드는 표준화된 JSON 문서입니다 — 고유 전달 식별자, 작업 식별자, 이벤트 유형, 이벤트 데이터, RFC 3339 타임스탬프, 그리고 테넌트 식별자입니다. 전달은 JSON 본문과 네 개의 헤더를 담은 HTTP POST입니다. 즉, HMAC-SHA256 서명, unix 초 타임스탬프, 전달 식별자, 그리고 이벤트 유형입니다. 서명은 등록의 시크릿으로 정규 기준 문자열 {timestamp}.{body}에 대해 계산되므로, 타임스탬프 헤더는 암호학적으로 본문에 바인딩됩니다. 수신자는 동일한 기준 문자열에 대해 HMAC를 다시 계산하고, 타임스탬프가 허용 가능한 신선도 창을 벗어난 전달을 거부하여 재생을 한정합니다.

전달은 지수 백오프를 사용합니다. 2xx 응답은 성공입니다. 429가 아닌 4xx 응답은 영구 거부로 취급되며 재시도하지 않습니다. 그 외 실패 — 5xx, 429, 또는 연결 오류 — 는 최댓값으로 제한된 두 배 증가 지연으로 정책의 시도 횟수까지 재시도합니다. 모든 시도가 소진되면 전달은 원래 페이로드, 시도 횟수, 마지막 오류, 그리고 마지막 HTTP 상태와 함께 인메모리 데드 레터 큐에 기록됩니다. 데드 레터 항목은 재생됨(replayed)으로 표시할 수 있습니다. 두 가지 재시도 정책이 제공됩니다 — default(5회 시도, 1s 기본, 5min 상한)와 aggressive(10회 시도, 2s 기본, 10min 상한).

이렇게 작동하는 이유

전달은 던져놓고 잊는(fire-and-forget) 호출이 아니라 운영 표면으로 취급됩니다. 실패는 의도에 따라 분류됩니다. 429가 아닌 4xx는 진정한 수신자 거부이므로 즉시 중단됩니다. 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
}

엣지 케이스 및 주의 사항

빈 이벤트 목록은 모두 구독합니다. 이벤트 유형이 없는 등록은 모든 이벤트를 받습니다. 스코프를 지정하려면 명시적 목록을 전달하십시오.
테넌트 격리가 적용됩니다. 컨텍스트 테넌트와 다른 테넌트 ID로 등록하는 것은 거부됩니다. 디스패치는 호출 테넌트의 활성 등록만 순회합니다.
4xx(429 제외)는 종료입니다. 429가 아닌 4xx는 재시도하지 않습니다 — 영구 수신자 거부로 취급되며 데드 레터 큐로 갑니다.
등록 해제는 소프트입니다. 등록 해제는 비활성화합니다. 레코드는 지속되며 디스패치에서 제외됩니다.
데드 레터 큐는 인메모리입니다. 프로세스 수명 내의 검사와 재생을 위한 것입니다. 재시작 간 영속적 재생이 필요하면 직접 항목을 영속화하십시오.

성능

디스패치 비용은 이벤트를 구독하는 테넌트의 활성 등록 수에 비례합니다. 각 전달은 서명된 기준 문자열에 대한 HMAC-SHA256 1회에 HTTP 왕복을 더한 것입니다. 재시도는 한정된 지수 백오프 지연을 추가합니다. 서명은 O(페이로드 크기)입니다.

보안 참고 사항

각 페이로드는 등록의 시크릿으로 키가 지정된 HMAC-SHA256 서명으로 인증되며 X-NextPDF-Signature 헤더에 sha256=<hex>로 전송됩니다. 서명은 {timestamp}.{body} 기준 문자열을 포괄하고, 타임스탬프는 X-NextPDF-Timestamp 헤더로 전달됩니다. 수신자는 상수 시간 비교로 검증하고 재생을 한정하기 위해 신선도 창을 벗어난 전달을 거부합니다. 대상 URL은 매 전송 전에 중앙 이그레스 게이트를 통과합니다. HTTPS가 필수이며, 사설, 루프백, 링크 로컬, 또는 클라우드 메타데이터 주소로 해석되는 호스트는 요청 없이 거부되고 데드 레터 큐로 라우팅됩니다. 서명 시크릿은 등록별입니다. 이를 자격 증명으로 취급하십시오. 서명은 페이로드 무결성과 출처를 인증합니다. 암호화 계층이 아닙니다 — 수신자가 보아서는 안 되는 시크릿을 이벤트 데이터에 두지 마십시오.

적합성

페이로드 인증은 SHA-256을 사용하는 HMAC, 즉 FIPS PUB 198-1의 키 해시 메시지 인증 코드를 사용합니다. OWASP ASVS 5.0은 승인된 메시지 인증 알고리즘 중 하나로 HMAC-SHA-256을 나열합니다.
페이로드 타임스탬프는 RFC 3339 날짜-시간 문자열입니다. 참고: 이 페이지에서는 RFC 3339가 RAG 코퍼스에서 검색되지 않았습니다. 형식은 코드 선언(RFC 3339 확장)이며 RAG 검증이 아니라 코드 선언으로 표시됩니다.

동작 계약

등록은 엄격하게 테넌트 스코프입니다. 일치하지 않는 테넌트로 등록하는 것은 거부되며 등록 해제는 이력을 보존하는 소프트 비활성화입니다.
빈 이벤트 목록은 모든 이벤트를 구독합니다. 이벤트 유형을 구독하는 활성 등록만 디스패치를 받습니다.
각 전달은 JSON 본문에 HMAC-SHA256 서명 헤더({timestamp}.{body} 기준 문자열에 대해), unix 초 타임스탬프 헤더, 전달 식별자, 그리고 이벤트 유형을 더한 HTTP POST입니다.
2xx는 성공입니다. 429가 아닌 4xx는 영구 거부입니다(재시도 없음). 5xx, 429, 또는 연결 오류는 상한이 있는 두 배 증가 백오프로 정책의 시도 횟수까지 재시도합니다.
소진된 시도는 전달을 인메모리 데드 레터 큐에 기록합니다(페이로드, 시도 횟수, 마지막 오류, 마지막 상태). 데드 레터 항목은 재생됨으로 표시할 수 있습니다.

게시 경계

이 페이지는 외부에서 관찰 가능한 동작과 지원되는 공개 API 표면만 문서화합니다. 내부 네임스페이스 경로, 헬퍼 클래스, 메커니즘 표, 런북 파일명, 그리고 티켓 접두사는 범위 밖입니다.

Core 폴백

NextPDF Core(Apache-2.0)에는 웹훅 등록 또는 전달 표면이 없습니다 — 전혀 없습니다. 이 역량에는 Core 등급에 해당하는 것이 없습니다.

Pro 폴백

NextPDF Pro에는 웹훅 등록 또는 전달 표면이 없습니다 — 전혀 없습니다. 이 역량에는 Pro 등급에 해당하는 것이 없습니다. 웹훅 매니저, 등록, 페이로드, 전달 엔진, 재시도 정책은 nextpdf/enterprise 패키지에만 포함됩니다.

Enterprise 경계 참고

재시도 정책, 백오프 일정, 데드 레터 처리는 동작 수준에서 설명됩니다. 데드 레터 큐는 프로세스 수명 내의 검사와 재생을 위한 인메모리입니다. 재시작 간 영속적 영속화와 모든 내부 전달 내부는 공개 표면의 범위 밖입니다.

배포 경계

운영자는 콜백 엔드포인트, 등록별 서명 시크릿(자격 증명으로 취급), 재시작 간 재생이 필요한 경우 데드 레터 항목의 영속적 영속화, 그리고 수신자 URL의 HTTPS 태세를 소유합니다. NextPDF Enterprise는 서명하고 전달하지만 프로세스 수명을 넘어 등록이나 데드 레터를 직접 영속화하지는 않습니다.

법률 준수 경계

웹훅 표면에는 어떠한 수출 통제 제한도 적용되지 않습니다. HMAC 서명은 페이로드 무결성과 출처를 인증합니다. 암호화 계층이 아닙니다 — 운영자는 수신자가 보아서는 안 되는 시크릿을 이벤트 데이터에 두어서는 안 됩니다. 이 문서는 법률 의견이 아닙니다. 자체 준수 및 법률 자문에게 문의하십시오.