Enterprise phiên bản

Webhook

Tổng quan nhanh

NextPDF Enterprise gửi các sự kiện công việc tới các endpoint webhook theo từng thuê bao qua HTTP POST, ký mỗi payload bằng một chữ ký HMAC-SHA256, thử lại với backoff theo cấp số nhân, và định tuyến các lần gửi thất bại vĩnh viễn tới một hàng đợi dead-letter để kiểm tra và phát lại. Trang này mô tả hành vi webhook có thể quan sát được và hợp đồng công khai.

Khả dụng & cấp phép

Năng lực này đi kèm trong NextPDF Enterprise (nextpdf/enterprise) và được kích hoạt bằng một envelope giấy phép bậc Enterprise. Một triển khai không có quyền đó sẽ không nạp các lớp của năng lực này. So sánh các phiên bản và lấy giấy phép.

Bề mặt webhook là một năng lực Enterprise cơ sở, sẵn dùng ngay khi gói Enterprise được cài đặt; không có cờ riêng theo từng tính năng.

Tổng quan khái niệm

Một thuê bao đăng ký một URL callback, một secret ký, và một danh sách loại sự kiện tùy chọn. Một danh sách sự kiện rỗng nghĩa là “theo dõi tất cả sự kiện”. Các đăng ký bị giới hạn nghiêm ngặt theo từng thuê bao: một thuê bao chỉ có thể thấy và quản lý các đăng ký của riêng mình, và việc đăng ký dưới một thuê bao không khớp sẽ bị từ chối. Việc hủy đăng ký vô hiệu hóa đăng ký thay vì xóa nó, nên lịch sử được giữ lại; chỉ các đăng ký đang hoạt động nhận các lần gửi.

Khi một sự kiện công việc được gửi cho một thuê bao, mỗi đăng ký đang hoạt động có theo dõi loại sự kiện sẽ nhận một lần gửi. Payload là một tài liệu JSON chuẩn hóa — một mã định danh lần gửi duy nhất, mã định danh công việc, loại sự kiện, dữ liệu sự kiện, một dấu thời gian RFC 3339, và mã định danh thuê bao. Lần gửi là một HTTP POST mang theo thân JSON và bốn header: một chữ ký HMAC-SHA256, một dấu thời gian tính bằng giây unix, mã định danh lần gửi, và loại sự kiện. Chữ ký được tính trên chuỗi cơ sở chuẩn tắc {timestamp}.{body} với secret của đăng ký, nên header dấu thời gian được ràng buộc bằng mật mã với thân. Bên nhận tính lại HMAC trên cùng chuỗi cơ sở đó và từ chối các lần gửi có dấu thời gian rơi ra ngoài một cửa sổ độ tươi chấp nhận được, điều này giới hạn khả năng phát lại.

Việc gửi dùng backoff theo cấp số nhân. Một phản hồi 2xx là thành công. Một phản hồi 4xx khác 429 được coi là một từ chối vĩnh viễn và không được thử lại. Các thất bại khác — 5xx, 429, hoặc một lỗi kết nối — được thử lại đến số lần thử của chính sách với một độ trễ nhân đôi giới hạn ở một mức tối đa. Khi tất cả các lần thử đã cạn, lần gửi được ghi lại trong một hàng đợi dead-letter trong bộ nhớ cùng payload gốc, số lần thử, lỗi cuối cùng, và trạng thái HTTP cuối cùng; một mục dead-letter có thể được đánh dấu đã phát lại. Hai chính sách thử lại đi kèm — một default (5 lần thử, cơ sở 1s, giới hạn 5min) và một aggressive (10 lần thử, cơ sở 2s, giới hạn 10min).

Vì sao nó hoạt động theo cách này

Việc gửi được coi là một bề mặt vận hành, không phải một lời gọi bắn-rồi-quên. Các thất bại được phân loại theo ý định. Một 4xx khác 429 là một từ chối thực sự của bên nhận, nên nó dừng ngay lập tức. Một 5xx, một 429, hoặc một lỗi kết nối là tạm thời, nên nó được hưởng một lần thử lại có giới hạn, có backoff. Các lần gửi đã cạn mọi lần thử không bao giờ bị bỏ đi âm thầm; chúng rơi vào một hàng đợi dead-letter có thể kiểm tra được và có thể được phát lại. Chữ ký ràng buộc một dấu thời gian vào chuỗi cơ sở của nó, và mọi đích đến đều vượt qua một cổng egress, nên tính xác thực và khả năng kháng phát lại được đảm bảo theo thiết kế cho từng thuê bao.

Bối cảnh thiết kế: Vận hành NextPDF trong sản phẩm.

Bề mặt API công khai

composer require nextpdf/enterprise:^3

Các điểm tích hợp được hỗ trợ là webhook manager (register, unregister, activeRegistrations, dispatch), value object đăng ký (subscribesTo, deactivate), payload (fromJobEvent, toJson, toArray, sign, signedTimestamp), engine gửi (deliver, deadLetters, clearDeadLetters), chính sách thử lại (delayForAttempt, shouldRetry, default, aggressive), và mục dead-letter (markReplayed).

Mẫu mã — bắt đầu nhanh

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

Xác minh phía bên nhận:

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

Mẫu mã — sản phẩm

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
}

Trường hợp ngoại lệ & lưu ý

Danh sách sự kiện rỗng theo dõi tất cả. Một đăng ký không có loại sự kiện nào nhận mọi sự kiện; hãy truyền một danh sách tường minh để giới hạn phạm vi của nó.
Cô lập thuê bao được thực thi. Việc đăng ký với một tenant ID khác với thuê bao trong ngữ cảnh sẽ bị từ chối; việc gửi chỉ duyệt qua các đăng ký đang hoạt động của thuê bao đang gọi.
4xx (ngoại trừ 429) là cuối cùng. Một 4xx khác 429 không được thử lại — nó được coi là một từ chối vĩnh viễn của bên nhận và đi tới hàng đợi dead-letter.
Hủy đăng ký là mềm. Việc hủy đăng ký vô hiệu hóa; bản ghi vẫn tồn tại và được loại khỏi việc gửi.
Hàng đợi dead-letter nằm trong bộ nhớ. Nó dành cho việc kiểm tra và phát lại trong vòng đời tiến trình; hãy tự lưu các mục nếu bạn cần phát lại bền vững xuyên các lần khởi động lại.

Hiệu năng

Chi phí gửi tỷ lệ thuận với số lượng đăng ký đang hoạt động cho thuê bao có theo dõi sự kiện. Mỗi lần gửi là một HMAC-SHA256 trên chuỗi cơ sở đã ký cộng với lượt khứ hồi HTTP; các lần thử lại bổ sung các độ trễ backoff theo cấp số nhân có giới hạn. Việc ký là O(kích thước payload).

Lưu ý bảo mật

Mỗi payload được xác thực bằng một chữ ký HMAC-SHA256 được lập khóa bởi secret của đăng ký và được gửi trong header X-NextPDF-Signature dưới dạng sha256=<hex>. Chữ ký bao trùm chuỗi cơ sở {timestamp}.{body}, và dấu thời gian đi trong header X-NextPDF-Timestamp; bên nhận xác minh bằng một phép so sánh theo thời gian hằng số và từ chối các lần gửi ngoài một cửa sổ độ tươi để giới hạn khả năng phát lại. Các URL đích vượt qua một cổng egress trung tâm trước mỗi lần gửi: HTTPS là bắt buộc, và các host phân giải thành các địa chỉ riêng tư, loopback, link-local, hoặc cloud-metadata bị từ chối mà không có một request và được định tuyến tới hàng đợi dead-letter. Secret ký là theo từng đăng ký; hãy coi nó là một thông tin xác thực. Chữ ký xác thực tính toàn vẹn và nguồn gốc của payload; nó không phải là một lớp mã hóa — đừng đặt các secret vào dữ liệu sự kiện mà bên nhận không nên thấy.

Tính phù hợp

Việc xác thực payload dùng HMAC với SHA-256, mã xác thực thông điệp băm-có-khóa của FIPS PUB 198-1; OWASP ASVS 5.0 liệt kê HMAC-SHA-256 trong số các thuật toán xác thực thông điệp được phê duyệt của nó.
Các dấu thời gian payload là các chuỗi date-time RFC 3339. Lưu ý: RFC 3339 không được truy xuất từ kho RAG cho trang này; định dạng được khai báo trong mã (RFC 3339 mở rộng) và được đánh dấu là khai báo trong mã thay vì đã xác minh bằng RAG.

Hợp đồng hành vi

Các đăng ký bị giới hạn nghiêm ngặt theo từng thuê bao; việc đăng ký dưới một thuê bao không khớp bị từ chối và hủy đăng ký là một thao tác vô hiệu hóa mềm giữ lại lịch sử.
Một danh sách sự kiện rỗng theo dõi tất cả sự kiện; chỉ các đăng ký đang hoạt động có theo dõi loại sự kiện nhận một lần gửi.
Mỗi lần gửi là một HTTP POST với thân JSON cộng một header chữ ký HMAC-SHA256 (trên chuỗi cơ sở {timestamp}.{body}), một header dấu thời gian tính bằng giây unix, mã định danh lần gửi, và loại sự kiện.
Một 2xx là thành công; một 4xx khác 429 là một từ chối vĩnh viễn (không thử lại); 5xx, 429, hoặc một lỗi kết nối được thử lại đến số lần thử của chính sách với backoff nhân đôi có giới hạn.
Các lần thử đã cạn ghi lần gửi trong một hàng đợi dead-letter trong bộ nhớ (payload, số lần thử, lỗi cuối cùng, trạng thái cuối cùng); một mục dead-letter có thể được đánh dấu đã phát lại.

Ranh giới công bố

Trang này chỉ ghi lại hành vi có thể quan sát được từ bên ngoài và bề mặt public API được hỗ trợ. Các đường dẫn namespace nội bộ, các lớp trợ giúp, các bảng cơ chế, các tên tệp runbook, và các tiền tố ticket nằm ngoài phạm vi.

Phương án dự phòng Core

NextPDF Core (Apache-2.0) không có bề mặt đăng ký hay gửi webhook nào — không hề có; năng lực này không có tương đương ở bậc Core.

Phương án dự phòng Pro

NextPDF Pro không có bề mặt đăng ký hay gửi webhook nào — không hề có; năng lực này không có tương đương ở bậc Pro. Webhook manager, đăng ký, payload, engine gửi, và chính sách thử lại chỉ đi kèm trong gói nextpdf/enterprise.

Lưu ý về ranh giới Enterprise

Chính sách thử lại, lịch backoff, và việc xử lý dead-letter được mô tả ở mức hành vi. Hàng đợi dead-letter nằm trong bộ nhớ để kiểm tra và phát lại trong vòng đời tiến trình; việc lưu bền vững xuyên khởi-động-lại và bất kỳ chi tiết nội bộ nào của việc gửi đều nằm ngoài phạm vi của bề mặt công khai.

Ranh giới triển khai

Người vận hành sở hữu các endpoint callback, các secret ký theo từng đăng ký (được coi là thông tin xác thực), việc lưu bền vững các mục dead-letter nếu cần phát lại xuyên khởi-động-lại, và lập trường HTTPS của các URL bên nhận. NextPDF Enterprise ký và gửi nhưng bản thân nó không lưu các đăng ký hay các dead letter vượt quá vòng đời tiến trình.

Ranh giới tuân thủ pháp lý

Không có hạn chế kiểm soát xuất khẩu nào áp dụng cho bề mặt webhook. Chữ ký HMAC xác thực tính toàn vẹn và nguồn gốc của payload; nó không phải là một lớp mã hóa — người vận hành không được đặt các secret vào dữ liệu sự kiện mà bên nhận không nên thấy. Tài liệu này không phải là một ý kiến pháp lý; hãy tham vấn các cố vấn tuân thủ và pháp lý của riêng bạn.