ข้ามไปยังเนื้อหาหลัก
ภาพรวม ภาพรวม ข่าว ข่าว
แชร์

Webhooks & เหตุการณ์

เหตุการณ์แบบเรียลไทม์. ส่งมอบพร้อมลายเซ็น HMAC.

PaperOffice จะเรียกใช้จุดปลายของคุณทันทีที่มีการเปลี่ยนแปลงเอกสาร โฟ่งาน พื้นที่ทำงาน หรืองาน ไม่ต้องมีการดึงข้อมูลซ้ำ

22 ประเภทเหตุการณ์, ลายเซ็น HMAC-SHA256, กลยุทธ์การลองใหม่สามแบบ และบันทึกการส่งมอบต่อครั้ง

HMAC-SHA256 ในทุกการส่งมอบ สูงสุด 10 ครั้ง (ค่าเริ่มต้น 5) Idempotent ตาม Event-ID

เหตุการณ์ที่มีอยู่

ประเภทเหตุการณ์ 22 ประเภท จัดกลุ่มตามเอนทิตี

สมัครรับเหตุการณ์รายตัวหรือใช้ตัวแทน * สำหรับทั้งหมด

เอกสาร

14
  • document.uploaded อัปโหลดเอกสารใหม่ไปยังพื้นที่ทำงาน
  • document.created นามแฝงสำหรับ document.uploaded (ความเข้ากันได้)
  • document.processed เสร็จสิ้นขั้นตอนการประมวลผล OCR/AI-IDP อย่างสำเร็จ
  • document.edited แก้ไขเอกสาร: อัปเดตข้อมูลเมตา แท็ก หรือเนื้อหา
  • document.deleted ย้ายเอกสารไปยังถังขยะ
  • document.restored กู้คืนเอกสารจากถังขยะ
  • document.moved ย้ายเอกสารระหว่างพื้นที่ทำงาน
  • document.version_created เวอร์ชันใหม่ของเอกสารที่มีอยู่
  • document.lifecycle_changed สถานะการเก็บรักษา/การจัดเก็บถาวรเปลี่ยนแปลง
  • document.comment_added ความคิดเห็นต่อเอกสารถูกสร้าง
  • document.note_added บันทึกภายในถูกแนบ
  • document.tag_added แท็กถูกกำหนดให้กับเอกสาร
  • document.legal_hold_placed Legal Hold เปิดใช้งาน (ไม่สามารถเปลี่ยนแปลงได้)
  • document.legal_hold_released Legal Hold ยกเลิก

งาน

3
  • job.completed งานแบบอะซิงโครนัสเสร็จสมบูรณ์
  • job.failed งานแบบอะซิงโครนัสล้มเหลวถาวร
  • job.progress อัปเดตความคืบหน้าสำหรับงานที่ยาวนาน

Workspaces

2
  • workspace.shared แบ่งปันพื้นที่ทำงานกับผู้ใช้หรือทีม
  • workspace.unshared เพิกถอนการเข้าถึงพื้นที่ทำงาน

งาน

3
  • task.created สร้างงานใหม่
  • task.completed ทำเครื่องหมายว่างานเสร็จสิ้นแล้ว
  • task.overdue งานเลยกำหนดส่งแล้ว

แพย์โหลดและส่วนหัว

การจัดส่งแต่ละครั้งจะปฏิบัติตามรูปแบบเดียวกัน

โครงสร้าง JSON ที่คาดเดาได้, HTTP Header คงที่, Timestamp ISO-8601 UTC

Request body

{
  "event_type": "document.processed",
  "event_id": "a3b7f9c1d4e8b2a6c9f1d4e7b2a5c8f1",
  "timestamp": "2026-04-17T14:23:11Z",
  "subscription_id": 42,
  "data": {
    "pofid": "doc_01HZY8K3M7P2Q9R5T1V6W4X2Y8",
    "workspace_id": 17,
    "filename": "invoice-2026-04-17.pdf",
    "mime_type": "application/pdf",
    "size_bytes": 284521,
    "processing_result": {
      "ocr_done": true,
      "classification": "invoice",
      "confidence": 0.98
    }
  }
}

ส่วนหัวของ HTTP Request

ส่วนหัว ตัวอย่างค่า ความหมาย
Content-Type application/json เป็น JSON เสมอ, เข้ารหัส UTF-8
User-Agent PaperOffice-Webhook/1.0 ตัวระบุคงที่สำหรับ Firewall Allowlists
X-PaperOffice-Event document.processed ประเภทเหตุการณ์ที่ส่งถึง
X-PaperOffice-Event-ID a3b7f9c1… ID ที่ไม่ซ้ำกันแบบ 128 บิต ใช้เป็นคีย์ Idempotency
X-PaperOffice-Subscription-ID 42 ID ของสมาชิกที่รับอีเวนต์
X-PaperOffice-Signature sha256=… HMAC-SHA256 ของ Raw Body ที่เข้ารหัสเป็น hex
cURL
curl -X POST "https://api.paperoffice.ai/latest/webhooks/subscribe" \  -H "Authorization: Bearer po_ut_YOUR_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "name": "My Production Webhook",    "url": "https://yourdomain.com/webhooks/paperoffice",    "events": ["document.processed", "job.completed", "job.failed"],    "retry_policy": "exponential",    "max_retries": 5,    "timeout_ms": 10000  }'

การตรวจสอบลายเซ็น

ยืนยันการจัดส่งทุกครั้งด้วย HMAC-SHA256

คำนวณ HMAC-SHA256 จาก raw request body โดยใช้ shared secret ของคุณ และเปรียบเทียบผลลัพธ์กับ X-PaperOffice-Signature — จำเป็นต้องใช้การเปรียบเทียบแบบ constant-time

  • การเปรียบเทียบแบบ constant-time

    hash_equals, hmac.compare_digest หรือ crypto.timingSafeEqual: การเปรียบเทียบต้องไม่เปิดเผยความแตกต่างของเวลาในการดำเนินการ

  • ลงนาม Rohen Body

    ลายเซ็นมีผลต่อ Request-Body ที่ไม่มีการเปลี่ยนแปลง โปรดแยกวิเคราะห์ JSON หลังจากตรวจสอบแล้ว มิฉะนั้นค่าแฮชจะคลาดเคลื่อน

  • สมัครสมาชิกผ่าน API

    POST /latest/webhooks/subscribe พร้อม name, url และ events หากเว้น secret ว่าง PaperOffice จะสร้างและคืนค่าให้เพียงครั้งเดียว

ลองใหม่และการส่งมอบ

กลยุทธ์ลองใหม่สามแบบ สูงสุด 10 ครั้ง

เลือกนโยบายต่อสมัครสมาชิก แต่ละความพยายามจะถูกบันทึกพร้อมสถานะโค้ด, เนื้อหาตอบกลับ และเวลา

  • ค่าเริ่มต้น exponential

    เอ็กซ์โพเนนเชียล (ค่าเริ่มต้น)

    ระยะห่างระหว่างการลองใหม่จะเพิ่มขึ้นเป็นสองเท่าหลังจากแต่ละครั้งที่ไม่สำเร็จ

  • linear

    เชิงเส้น

    ระยะห่างระหว่างการลองใหม่เพิ่มขึ้นตามขั้นตอนคงที่

  • none

    ไม่มี

    ไม่มีการลองใหม่ แม้ในกรณีของข้อผิดพลาดระดับ 5xx (ส่งแล้วลืม) มีประโยชน์สำหรับฮุกทดสอบ

  • สำเร็จ HTTP 2xx ภายในหน้าต่างเวลาหมดอายุ
  • จำนวนการลองใหม่สูงสุด สูงสุด 10 ครั้ง (ค่าเริ่มต้นคือ 5)
  • เวลาหมดอายุ 1.000–30.000 มิลลิวินาทีต่อครั้ง (ค่าเริ่มต้น 10.000)
  • บันทึกการจัดส่ง ทุกครั้งที่มีการดำเนินการจะถูกบันทึก; บันทึกจะคงอยู่แม้หลังจากการลบการสมัครรับข้อมูลแล้ว

การจัดการ-API

ห้าจุดสิ้นสุดภายใต้ /latest/webhooks/

สร้าง, แสดงรายการ, อัปเดต และลบการสมัครรับข้อมูล — รวมถึงจุดสิ้นสุดสำหรับการทดสอบ การเรียกใช้แต่ละครั้งต้องใช้โทเค็น Bearer

  • POST /webhooks/subscribe สร้างการสมัครรับข้อมูล; โหลดจะถูกลงนามด้วย HMAC-SHA256 เครื่องมือ MCPpo-webhooks-subscribe
  • GET /webhooks/list แสดงรายการการสมัครรับข้อมูลเว็บฮุคทั้งหมดของบัญชี เครื่องมือ MCPpo-webhooks-list
  • POST /webhooks/update อัปเดต URL, เหตุการณ์, ส่วนหัว, นโยบายการลองใหม่ หรือสถานะที่ใช้งาน เครื่องมือ MCPpo-webhooks-update
  • POST /webhooks/delete ยกเลิกการสมัครรับข้อมูล; บันทึกการจัดส่งจะคงอยู่ เครื่องมือ MCPpo-webhooks-delete
  • POST /webhooks/test ส่งเหตุการณ์ทดสอบไปยังการสมัครรับข้อมูลและตรวจสอบการจัดส่ง เครื่องมือ MCPpo-webhooks-test

ความปลอดภัย

ออกแบบมาให้ปลอดภัยตั้งแต่เริ่มต้น

หกกลไกที่ทำงานในทุกการจัดส่ง — ทั้งจากฝั่ง PaperOffice และฝั่งของคุณ

  • HMAC-SHA256

    การจัดส่งแต่ละครั้งจะถูกเซ็นด้วย Secret ของคุณ การเปรียบเทียบต้องเกิดขึ้นในเวลาคงที่เสมอ

  • การป้องกัน SSRF

    IP ส่วนตัวและภายใน, Localhost และจุดสิ้นสุดเมตาดาตาของคลาวด์จะถูกบล็อกทั้งตอนสมัครสมาชิกและตอนส่งข้อมูล

  • ปลอดภัยจากการโจมตี DNS Rebinding

    IP จะถูกตรวจสอบความถูกต้องอีกครั้งในระหว่าง Dispatch และถูกตรึงไว้ด้วย CURLOPT_RESOLVE

  • แนะนำ HTTPS

    รองรับทั้ง http และ https แต่สำหรับการใช้งานจริงแนะนำให้ใช้ HTTPS

  • ความซ้ำซ้อนของเหตุการณ์ผ่าน Event-ID

    การส่งข้อมูลแต่ละครั้งจะมี X-PaperOffice-Event-ID ที่ไม่ซ้ำกัน โปรดทำการลบข้อมูลซ้ำด้านของคุณ

  • บันทึกการส่งข้อมูลอย่างสมบูรณ์

    ทุกความพยายามจะถูกบันทึก: สถานะโค้ด, เนื้อหา Response, การวัดเวลา, ข้อความข้อผิดพลาด

ขีดจำกัด

กำหนดพฤติกรรมการจัดส่งได้สำหรับแต่ละการสมัครสมาชิก

ตั้งค่าค่าทั้งหมดได้เมื่อสร้างหรือภายหลังผ่าน /webhooks/update — สำหรับแต่ละการสมัครสมาชิก ไม่ใช่สำหรับแต่ละบัญชี

  • 0–10 จำนวนครั้งซ้ำต่อการจัดส่ง (ค่าเริ่มต้น 5)
  • 1,000–30,000 มิลลิวินาที เวลาหมดอายุต่อการลองทำ (ค่าเริ่มต้น 10,000)
  • 3 นโยบายการลองใหม่: none, linear, exponential
  • HMAC-SHA256 ลายเซ็นในการจัดส่งทุกครั้ง

Webhooks มีให้บริการตั้งแต่แผน Professional แผนใดเหมาะกับเซตอัปของคุณ ดูได้จากหน้าสรุปราคา

วิดีโอ

Webhooks ในการทำงานจริง

ชมว่า PaperOffice Webhooks ทำงานอย่างไรในทางปฏิบัติ — ผ่านวิดีโอ

Webhooks ในการทำงานจริง

คำถาม

คำถามที่พบบ่อยเกี่ยวกับ Webhooks

ฉันจะยืนยันการจัดส่งได้อย่างไร?

คำนวณ HMAC-SHA256 จาก body ของ request ดิบ โดยใช้ secret ของการสมัครสมาชิกของคุณ แล้วเปรียบเทียบผลลัพธ์แบบคงที่เวลา (constant time) กับส่วนหัว X-PaperOffice-Signature (รูปแบบ sha256=<hex>) หากลายเซ็นไม่ตรง ให้ตอบกลับด้วย HTTP 401 และไม่ต้องประมวลผล body

Secret มาจากไหน?

เมื่อสร้างการสมัครสมาชิกผ่าน POST /latest/webhooks/subscribe หากปล่อยฟิลด์ secret ว่าง PaperOffice จะสร้าง secret ขึ้นมาและส่งคืนเพียงครั้งเดียวในคำตอบ คุณสามารถแทนที่มันได้ตลอดเวลาผ่าน POST /latest/webhooks/update

เกิดอะไรขึ้นหาก endpoint ของฉันไม่ตอบกลับ?

การตอบกลับใดๆ ที่อยู่นอกเหนือจาก HTTP 2xx หรือการหมดเวลาจะนับเป็นการลองส่งที่ไม่สำเร็จ PaperOffice จะทำการส่งซ้ำตามนโยบาย Retry (แบบเอ็กซ์โพเนนเชียล, แบบเชิงเส้น, หรือไม่มี) จนกว่าจะถึงจำนวนครั้งที่กำหนดไว้ (0–10 ค่าเริ่มต้นคือ 5) แต่ละครั้งจะถูกบันทึกไว้ในบันทึกการส่งพร้อมรหัสสถานะ เนื้อหาตอบกลับ และเวลาที่ใช้

การส่งข้อมูลเดียวกันสามารถมาถึงได้สองครั้งหรือไม่?

เป็นไปได้ หากมีการลองส่งซ้ำหลังจากหมดเวลา ดังนั้นควรใช้ X-PaperOffice-Event-ID เพื่อทำการลดความซ้ำซ้อน (Deduplication) โดย ID นี้จะระบุเฉพาะสำหรับแต่ละ Event และสามารถใช้เป็นคีย์สำหรับ Idempotency ในฐานข้อมูลของคุณได้

ฉันสามารถสมัครรับ Event ประเภทใดได้บ้าง?

Event 22 ประเภทจาก 4 กลุ่ม: เอกสาร, งาน, พื้นที่ทำงาน และงานที่คุณต้องทำ คุณสามารถสมัครรับ Event เฉพาะเจาะจง หรือใช้ตัวแทน * เพื่อรับทั้งหมด นอกจากนี้ยังสามารถกรองการสมัครรับข้อมูลด้วยพารามิเตอร์เช่น workspace_id หรือ pofid ได้

Webhooks รวมอยู่ในแพ็กเกจใดบ้าง?

Webhooks มีให้บริการในแพ็กเกจ Professional ขึ้นไป แพ็กเกจที่เหมาะสมกับการตั้งค่าของคุณสามารถดูได้จากตารางราคา

การดำเนินงานและความน่าเชื่อถือ

สิ่งที่ทีมองค์กรตรวจสอบก่อนการโทรครั้งแรก

สัญญา ความปลอดภัย การสนับสนุน และขีดจำกัด ทั้งหมดเชื่อมโยงในที่เดียว

ท่านต้องการทดลอง PaperOffice ที่ใด

คอมพิวเตอร์และสมาร์ทโฟนเชื่อมต่อกันแล้ว: เวิร์กสเปซบนเครื่อง, บันทึกผ่านโทรศัพท์

เวอร์ชันทดสอบของคุณพร้อมใช้งานแล้ว

คุณต้องการเริ่มต้นที่ไหน?

เวิร์กสเปซเต็มรูปแบบได้รับการปรับให้เหมาะสมสำหรับคอมพิวเตอร์ เวอร์ชันมือถือเหมาะสำหรับการบันทึก ตรวจสอบ และอนุมัติเอกสาร

app.paperoffice.ai

เริ่มต้นบนคอมพิวเตอร์

เราจะส่งลิงก์การเข้าถึงส่วนบุคคลของคุณไปยังที่อยู่อีเมลของคุณ

สมัครฟรี เปิดแอป แอป PaperOffice ผลิตภัณฑ์เต็มรูปแบบ: เว็บ เดสก์ท็อป และมือถือ จับภาพ จัดระเบียบ ค้นหา และทำงานกับเอกสารร่วมกับทีม ต้องมีบัญชีฟรี เปิด Playground Playground ทดลองฟังก์ชันที่เลือกทันที — ไม่ต้องลงทะเบียน โดยใช้คีย์ API สาธิตแบบจำกัด ไม่ต้องลงทะเบียน แต่ใช้คีย์ API สาธิตแบบจำกัด