Webhook

ภาพรวมโดยสังเขป

NextPDF Enterprise ส่ง job event ไปยัง endpoint webhook ต่อ tenant ผ่าน HTTP POST ลงนาม payload แต่ละรายการด้วยลายเซ็น HMAC-SHA256 ลองใหม่ด้วย exponential backoff และกำหนดเส้นทางการส่งที่ล้มเหลวถาวรไปยังคิว dead-letter เพื่อการตรวจสอบและ replay หน้านี้อธิบายพฤติกรรม webhook ที่สังเกตได้และสัญญาสาธารณะ

ความพร้อมใช้งานและสิทธิ์การใช้งาน

ความสามารถนี้มาพร้อม NextPDF Enterprise ( nextpdf/enterprise ) และเปิดใช้งานด้วย envelope สิทธิ์การใช้งานระดับ Enterprise การปรับใช้ที่ไม่มีสิทธิ์นั้นจะไม่โหลดคลาสของความสามารถ เปรียบเทียบรุ่นและขอรับสิทธิ์การใช้งาน

พื้นผิว webhook เป็นความสามารถพื้นฐานของ Enterprise ที่พร้อมใช้งานเมื่อติดตั้งแพ็กเกจ Enterprise แล้ว ไม่มีแฟล็กต่อฟีเจอร์แยกต่างหาก

ภาพรวมเชิงแนวคิด

tenant ลงทะเบียน callback URL, signing secret และรายการ event type ที่ไม่บังคับ รายการ event ที่ว่างเปล่าหมายถึง “สมัครรับ event ทั้งหมด” การลงทะเบียนมีขอบเขตด้วย tenant อย่างเข้มงวด คือ tenant เห็นและจัดการได้เฉพาะการลงทะเบียนของตัวเอง และการลงทะเบียนภายใต้ tenant ที่ไม่ตรงกันจะถูกปฏิเสธ การยกเลิกการลงทะเบียนปิดใช้งานการลงทะเบียนแทนที่จะลบทิ้ง ดังนั้นประวัติจึงถูกรักษาไว้ มีเฉพาะการลงทะเบียนที่ใช้งานอยู่เท่านั้นที่ได้รับการ dispatch

เมื่อ job event ถูก dispatch สำหรับ tenant การลงทะเบียนที่ใช้งานอยู่แต่ละรายการที่สมัครรับ event type นั้นจะได้รับการส่ง payload เป็นเอกสาร JSON ที่เป็นมาตรฐาน — delivery identifier ที่ไม่ซ้ำ, job identifier, event type, event data, RFC 3339 timestamp และ tenant identifier การส่งเป็น HTTP POST ที่พา JSON body และ header สี่ตัว ได้แก่ ลายเซ็น HMAC-SHA256, timestamp แบบ unix-seconds, delivery identifier และ event type ลายเซ็นถูกคำนวณเหนือ base string ตามบัญญัติ {timestamp}.{body} ด้วย secret ของการลงทะเบียน ดังนั้น timestamp header จึงถูกผูกกับ body ด้วยการเข้ารหัส ผู้รับคำนวณ HMAC ซ้ำเหนือ base string เดียวกันและปฏิเสธการส่งที่ timestamp อยู่นอกหน้าต่างความสดที่ยอมรับได้ ซึ่งจำกัดการ replay

การส่งใช้ exponential backoff การตอบสนอง 2xx คือสำเร็จ การตอบสนอง 4xx อื่นที่ไม่ใช่ 429 ถือเป็นการปฏิเสธถาวรและไม่ถูกลองใหม่ ความล้มเหลวอื่น ๆ — 5xx, 429 หรือ connection error — ถูกลองใหม่ได้สูงสุดตามจำนวนความพยายามของนโยบายด้วย delay ที่เพิ่มเป็นสองเท่าและจำกัดที่ค่าสูงสุด เมื่อความพยายามทั้งหมดหมดลง การส่งจะถูกบันทึกในคิว dead-letter ในหน่วยความจำพร้อม payload เดิม, จำนวนความพยายาม, ข้อผิดพลาดล่าสุด และสถานะ HTTP ล่าสุด รายการ dead-letter สามารถถูกทำเครื่องหมายว่า replayed มีนโยบายการลองใหม่สองแบบที่มาพร้อม — default (5 ความพยายาม, base 1s, จำกัด 5min) และ aggressive (10 ความพยายาม, base 2s, จำกัด 10min)

เหตุใดจึงทำงานแบบนี้

การส่งถือเป็นพื้นผิวเชิงปฏิบัติการ ไม่ใช่การเรียกแบบ fire-and-forget ความล้มเหลวถูกจำแนกตามเจตนา 4xx อื่นที่ไม่ใช่ 429 เป็นการปฏิเสธจากผู้รับจริง จึงหยุดทันที ส่วน 5xx, 429 หรือ connection error เป็นแบบชั่วคราว จึงได้รับการลองใหม่แบบมีขอบเขตและ backoff การส่งที่ใช้ทุกความพยายามจนหมดจะไม่ถูกทิ้งเงียบ ๆ แต่จะไปอยู่ในคิว dead-letter ที่ตรวจสอบได้และสามารถ replay ได้ ลายเซ็นผูก timestamp ไว้ใน base string และทุกปลายทางต้องผ่าน egress gate ดังนั้นความถูกต้องแท้จริงและความต้านทานต่อการ replay จึงมั่นคงตามการออกแบบสำหรับแต่ละ tenant

พื้นหลังการออกแบบ: การใช้งาน NextPDF ในการผลิตจริง

พื้นผิว API สาธารณะ

composer require nextpdf/enterprise:^3

จุดผสานรวมที่รองรับคือ webhook manager (register, unregister, activeRegistrations, dispatch), ออบเจกต์ค่าการลงทะเบียน (subscribesTo, deactivate), payload (fromJobEvent, toJson, toArray, sign, signedTimestamp), delivery engine (deliver, deadLetters, clearDeadLetters), นโยบายการลองใหม่ (delayForAttempt, shouldRetry, default, aggressive) และรายการ dead-letter (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
}

กรณีขอบและข้อควรระวัง

• รายการ event ว่างเปล่าสมัครรับทั้งหมด การลงทะเบียนที่ไม่มี event type จะรับ event ทุกแบบ ส่งรายการที่ชัดเจนเพื่อกำหนดขอบเขต
• การแยก tenant ถูกบังคับใช้ การลงทะเบียนด้วย tenant ID ที่ต่างจาก tenant ของ context จะถูกปฏิเสธ การ dispatch วนซ้ำเฉพาะการลงทะเบียนที่ใช้งานอยู่ของ tenant ที่เรียกใช้
• 4xx (ยกเว้น 429) เป็น terminal 4xx อื่นที่ไม่ใช่ 429 จะไม่ถูกลองใหม่ — มันถือเป็นการปฏิเสธถาวรของผู้รับและไปยังคิว dead-letter
• การยกเลิกการลงทะเบียนเป็นแบบ soft การยกเลิกการลงทะเบียนปิดใช้งาน บันทึกยังคงอยู่และถูกกันออกจากการ dispatch
• คิว dead-letter อยู่ในหน่วยความจำ มันมีไว้สำหรับการตรวจสอบและ replay ภายในอายุของกระบวนการ ให้เก็บรายการเองหากต้องการการ replay แบบคงทนข้ามการรีสตาร์ท

ประสิทธิภาพ

ต้นทุนการ dispatch แปรผันตามจำนวนการลงทะเบียนที่ใช้งานอยู่ของ tenant ที่สมัครรับ event การส่งแต่ละครั้งคือ HMAC-SHA256 หนึ่งครั้งเหนือ base string ที่ลงนามบวกการรับส่งข้อมูลไปกลับ HTTP การลองใหม่เพิ่ม delay แบบ exponential-backoff ที่มีขอบเขต การลงนามเป็น O(payload size)

บันทึกด้านความปลอดภัย

payload แต่ละรายการถูกตรวจสอบสิทธิ์ด้วยลายเซ็น HMAC-SHA256 ที่ใช้คีย์เป็น secret ของการลงทะเบียน และถูกส่งใน header X-NextPDF-Signature เป็น sha256=<hex> ลายเซ็นครอบคลุม base string {timestamp}.{body} และ timestamp เดินทางใน header X-NextPDF-Timestamp ผู้รับตรวจสอบด้วยการเปรียบเทียบในเวลาคงที่และปฏิเสธการส่งที่อยู่นอกหน้าต่างความสดเพื่อจำกัดการ replay URL ปลายทางต้องผ่าน egress gate ส่วนกลางก่อนการส่งทุกครั้ง คือต้องเป็น HTTPS และ host ที่ resolve ไปยังที่อยู่แบบ private, loopback, link-local หรือ cloud-metadata จะถูกปฏิเสธโดยไม่มีการร้องขอและถูกกำหนดเส้นทางไปยังคิว dead-letter signing secret เป็นแบบต่อการลงทะเบียน ให้ถือเป็นข้อมูลรับรอง ลายเซ็นยืนยันความครบถ้วนและที่มาของ payload ไม่ใช่เลเยอร์การเข้ารหัส — อย่าใส่ข้อมูลลับใน event data ที่ผู้รับไม่ควรเห็น

ความสอดคล้อง

• การตรวจสอบสิทธิ์ payload ใช้ HMAC ด้วย SHA-256 ซึ่งเป็น keyed-hash message authentication code ของ FIPS PUB 198-1; OWASP ASVS 5.0 ระบุ HMAC-SHA-256 ไว้ในบรรดาอัลกอริทึม message-authentication ที่ได้รับการอนุมัติ
• timestamp ของ payload เป็นสตริง RFC 3339 date-time หมายเหตุ: RFC 3339 ไม่ได้ถูกดึงมาจากคลังข้อมูล RAG สำหรับหน้านี้ รูปแบบประกาศไว้ในโค้ด (RFC 3339 extended) และถูกทำเครื่องหมายว่าประกาศไว้ในโค้ดแทนที่จะเป็นแบบ RAG-verified

สัญญาพฤติกรรม

• การลงทะเบียนมีขอบเขตด้วย tenant อย่างเข้มงวด การลงทะเบียนภายใต้ tenant ที่ไม่ตรงกันจะถูกปฏิเสธ และการยกเลิกการลงทะเบียนเป็นการปิดใช้งานแบบ soft ที่รักษาประวัติไว้
• รายการ event ที่ว่างเปล่าสมัครรับ event ทั้งหมด มีเฉพาะการลงทะเบียนที่ใช้งานอยู่ซึ่งสมัครรับ event type เท่านั้นที่ได้รับการ dispatch
• การส่งแต่ละครั้งเป็น HTTP POST ที่มี JSON body บวกกับ header ลายเซ็น HMAC-SHA256 (เหนือ base string {timestamp}.{body}), header timestamp แบบ unix-seconds, delivery identifier และ event type
• 2xx คือสำเร็จ; 4xx อื่นที่ไม่ใช่ 429 เป็นการปฏิเสธถาวร (ไม่ลองใหม่); 5xx, 429 หรือ connection error ถูกลองใหม่ได้สูงสุดตามจำนวนความพยายามของนโยบายด้วย backoff แบบเพิ่มสองเท่าที่จำกัด
• ความพยายามที่หมดลงบันทึกการส่งในคิว dead-letter ในหน่วยความจำ (payload, จำนวนความพยายาม, ข้อผิดพลาดล่าสุด, สถานะล่าสุด) รายการ dead-letter สามารถถูกทำเครื่องหมายว่า replayed

ขอบเขตการเผยแพร่

หน้านี้อธิบายเฉพาะพฤติกรรมที่สังเกตได้จากภายนอกและพื้นผิว API สาธารณะที่รองรับเท่านั้น เส้นทาง namespace ภายใน, คลาสตัวช่วย, ตารางกลไก, ชื่อไฟล์ runbook และคำนำหน้า ticket อยู่นอกขอบเขต

ทางเลือกสำรองของ Core

NextPDF Core (Apache-2.0) ไม่มีพื้นผิวการลงทะเบียนหรือการส่ง webhook — ไม่มีเลย ความสามารถนี้ไม่มีสิ่งเทียบเท่าในระดับชั้น Core

ทางเลือกสำรองของ Pro

NextPDF Pro ไม่มีพื้นผิวการลงทะเบียนหรือการส่ง webhook — ไม่มีเลย ความสามารถนี้ไม่มีสิ่งเทียบเท่าในระดับชั้น Pro webhook manager, การลงทะเบียน, payload, delivery engine และนโยบายการลองใหม่ มาในแพ็กเกจ nextpdf/enterprise เท่านั้น

หมายเหตุขอบเขตของ Enterprise

นโยบายการลองใหม่ กำหนดการ backoff และการจัดการ dead-letter ได้รับการอธิบายในระดับพฤติกรรม คิว dead-letter อยู่ในหน่วยความจำสำหรับการตรวจสอบและ replay ภายในอายุของกระบวนการ การเก็บแบบคงทนข้ามการรีสตาร์ทและรายละเอียดภายในของการส่งใด ๆ อยู่นอกขอบเขตของพื้นผิวสาธารณะ

ขอบเขตการปรับใช้

ผู้ดำเนินการเป็นเจ้าของ endpoint callback, signing secret ต่อการลงทะเบียน (ถือเป็นข้อมูลรับรอง), การเก็บรายการ dead-letter แบบคงทนหากต้องการการ replay ข้ามการรีสตาร์ท และท่าที HTTPS ของ URL ผู้รับ NextPDF Enterprise ลงนามและส่ง แต่ไม่ได้เก็บการลงทะเบียนหรือ dead letter เองเกินอายุของกระบวนการ

ขอบเขตการปฏิบัติตามกฎหมาย

ไม่มีข้อจำกัดด้านการควบคุมการส่งออกที่มีผลกับพื้นผิว webhook ลายเซ็น HMAC ยืนยันความครบถ้วนและที่มาของ payload ไม่ใช่เลเยอร์การเข้ารหัส — ผู้ดำเนินการต้องไม่ใส่ข้อมูลลับใน event data ที่ผู้รับไม่ควรเห็น เอกสารนี้ไม่ใช่คำให้ความเห็นทางกฎหมาย โปรดปรึกษาที่ปรึกษาด้านการปฏิบัติตามข้อกำหนดและด้านกฎหมายของคุณเอง

ดูเพิ่มเติม

• Webhook — เอกสารอ้างอิงเชิงลึก
• SaaS — NextPDF Enterprise
• Metering — NextPDF Enterprise
• Licensing — NextPDF Enterprise