ภาพรวมของเว็บฮุก

Sursa บันทึก อีเวนต์ สำหรับทุกการเปลี่ยนแปลงที่สำคัญ เช่น การ์ดถูกเผยแพร่ ผ่านการตรวจสอบ หรือถูกเก็บเข้าคลัง มีผู้อ่านประกาศ หรือมีคำถามที่ยังไม่ได้รับคำตอบ คุณรับอีเวนต์ได้สองวิธี และใช้ทั้งสองวิธีร่วมกันได้:

	เว็บฮุก	ฟีดอีเวนต์
วิธีการ	Sursa ส่งแต่ละอีเวนต์ไปยังที่อยู่ HTTPS ของคุณทันทีที่เกิดขึ้น	คุณอ่าน `GET /v1/webhook-events` เมื่อใดก็ได้ที่ต้องการ
ความหน่วง	ไม่กี่วินาที	ตามความถี่ที่คุณโพล
สิ่งที่ต้องมี	เซิร์ฟเวอร์ผู้รับ HTTPS ที่เข้าถึงได้จากภายนอก	เพียงคีย์ API ที่มีบทบาท `admin` และขอบเขตสิทธิ์ `webhooks:manage`
เหมาะสำหรับ	ตอบสนองต่อการเปลี่ยนแปลง เช่น แจ้งเตือน ซิงก์ หรือเริ่มเวิร์กโฟลว์	งานแบบชุด การตามเก็บข้อมูลหลังระบบหยุดทำงาน และการตรวจเทียบ

ทั้งสองวิธีนำส่งอีเวนต์เดียวกันด้วย ID เดียวกัน ทุกอีเวนต์เก็บไว้ในฟีด 30 วัน ไม่ว่าจะมีเว็บฮุกใดสมัครรับอีเวนต์นั้นหรือไม่

อีเวนต์

{
  "id": "evt_0123456789abcdef0123456789abcdef",
  "type": "card.updated",
  "created_at": "2026-10-24T10:00:03Z",
  "org_id": 1,
  "api_version": "1.60.0",
  "sequence": 1042,
  "object": {"type": "card", "id": "3f2c9a7e-5b1d-4c8e-9f0a-1b2c3d4e5f60"},
  "payload": "full",
  "data": {
    "card": {"id": "3f2c9a7e-5b1d-4c8e-9f0a-1b2c3d4e5f60", "title": "Refund policy", "collection": "support", "version": 4},
    "actor_id": 7,
    "previous_attributes": {"title": "Refunds"}
  },
  "test": false
}

ฟิลด์	ความหมาย
`id`	ID ของอีเวนต์ ประกอบด้วย `evt_` และอักขระฐานสิบหก 32 ตัว มีค่าเดียวกันในทุกความพยายามส่งและในฟีด
`type`	สิ่งที่เกิดขึ้น ในรูป `<object>.<past-tense verb>` เช่น `card.updated` และ `access_request.resolved`
`created_at`	เวลาที่การเปลี่ยนแปลงเกิดขึ้น ใน UTC
`api_version`	เวอร์ชันของ API ที่ `data` ใช้สคีมาตาม
`object`	ประเภทและ ID ของออบเจ็กต์ที่อีเวนต์เกี่ยวข้อง
`data`	รายละเอียด โครงสร้างขึ้นอยู่กับประเภทและอธิบายไว้ในแค็ตตาล็อกอีเวนต์
`data.previous_attributes`	ในอีเวนต์ `*.updated` คือค่าก่อนหน้าของฟิลด์ที่เปลี่ยนแปลง
`sequence` `payload` และ `test`	มีเฉพาะในการส่งของเว็บฮุก คือตำแหน่งในลำดับการส่งของเว็บฮุก โหมดเพย์โหลด และบอกว่าเป็นอีเวนต์ทดสอบหรือไม่

data มีเฉพาะสิ่งที่ผู้อ่านออบเจ็กต์คนใดก็ตามมองเห็นได้ผ่าน API ไม่มีรายการสิทธิ์เข้าถึง สิทธิ์ของผู้อื่น หรือฟิลด์ที่ซ่อนไว้เลย เหตุผลในอีเวนต์เป็นรหัสกลางแบบสั้น เช่น no_hits restricted หรือ index_failed

ประเภทอีเวนต์

อีเวนต์ครอบคลุมด้านต่อไปนี้:

ด้าน	ตัวอย่าง
การ์ด	`card.created` `card.updated` `card.published` `card.archived` `card.deleted` `card.indexed` และ `card.index_failed`
การตรวจสอบ	`card.verified` `card.unverified` `verification.expired` และ `verification.requested`
โครงสร้าง	`collection.created` และ `folder.updated`
การทำงานร่วมกัน	`comment.created` `draft.publish_requested` `announcement.sent` และ `announcement.read`
คำตอบ	`question.unanswered` `question.feedback_created` และ `access_request.created`
บุคคลและสิทธิ์เข้าถึง	`user.created` `user.deactivated` `group.member_added` และ `api_key.expiring`
แหล่งข้อมูลและการนำเข้า	`source.sync_completed` `import.sync_completed` และ `import.document_failed`
งานประมวลผล	`job.completed` `job.failed` และ `export.ready`
เว็บฮุก	`webhook.endpoint_disabled` และ `webhook.ping`

รายการทั้งหมดพร้อมสคีมาและตัวอย่างของแต่ละอีเวนต์อยู่ในแค็ตตาล็อกอีเวนต์ของ เอกสารอ้างอิง API ส่วน GET /v1/webhooks/catalog ส่งคืนประเภทที่มีให้ใช้ในระบบที่ติดตั้งของคุณ

ประเภทอีเวนต์ใหม่จะเพิ่มเข้ามาเรื่อยไป และอีเวนต์ที่มีอยู่ก็ได้ฟิลด์เพิ่ม ประเภทอีเวนต์จะไม่ถูกเปลี่ยนชื่อหรือนำออก เซิร์ฟเวอร์ผู้รับต้องข้ามประเภทและฟิลด์ที่ไม่รู้จัก

ใครได้รับอะไร

เว็บฮุกได้รับอีเวนต์ก็ต่อเมื่อเว็บฮุกนั้นมองเห็นออบเจ็กต์ของอีเวนต์ได้ ในแบบเดียวกับคีย์ API คือตามบทบาท โปรไฟล์ข้อมูล และคอลเลกชันของเว็บฮุก เว็บฮุกที่จำกัดไว้ที่คอลเลกชัน support จะไม่ได้รับอีเวนต์เกี่ยวกับการ์ดใน finance เลย อีเวนต์เกี่ยวกับบุคคล คีย์ แหล่งข้อมูล การนำเข้า งานประมวลผล การส่งออก การเรียกเก็บเงิน แอปพลิเคชัน และตัวเว็บฮุกเอง ส่งถึงเฉพาะเว็บฮุกที่มีบทบาท admin

ภายในขอบเขตนั้น เว็บฮุกแต่ละรายการเลือกอีเวนต์ของตัวเองได้:

ตามประเภท ด้วยมาสก์ เช่น card.* สำหรับทุกอีเวนต์ของการ์ด และ * สำหรับทุกอีเวนต์
ตามคอลเลกชันและตามแท็ก สำหรับอีเวนต์ของการ์ด

โหมดเพย์โหลดของเว็บฮุกคือ full (อีเวนต์พร้อม data ซึ่งเป็นค่าเริ่มต้น) หรือ thin (อีเวนต์ที่ไม่มี data เซิร์ฟเวอร์ผู้รับอ่านออบเจ็กต์ผ่าน API ด้วยคีย์ของตัวเอง และเห็นสถานะปัจจุบันเสมอ)

การส่งโดยสรุป

คำขอ HTTPS POST ที่มีอีเวนต์เป็น JSON ลงนามด้วยข้อมูลลับของเว็บฮุกในสองรูปแบบ ได้แก่ Standard Webhooks (webhook-signature) และ X-KB-Signature แบบเดิม
การตอบกลับ 2xx ใดก็ตามภายใน 10 วินาทีถือว่าสำเร็จ
การส่งที่ล้มเหลวจะลองส่งใหม่ต่อเนื่องเกือบสามวันโดยเว้นระยะนานขึ้นทุกครั้ง ระบบปฏิบัติตาม Retry-After ในการตอบกลับ 429 หรือ 503 การตอบกลับ 410 จะปิดใช้งานเว็บฮุก และความล้มเหลว 10 ครั้งติดต่อกันจะหยุดเว็บฮุกชั่วคราวจนกว่าจะเปิดใช้ต่อ
การส่งไปยังเว็บฮุกเดียวกันเป็นไปตามลำดับอย่างเคร่งครัด เว็บฮุกที่ตอบช้าไม่ทำให้เว็บฮุกอื่นล่าช้า
อีเวนต์เดียวกันอาจมาถึงมากกว่าหนึ่งครั้ง ให้ตัดรายการซ้ำด้วย webhook-id

รับเว็บฮุก แสดงเซิร์ฟเวอร์ผู้รับที่สมบูรณ์ทีละขั้นตอน พร้อมการตรวจลายเซ็นใน Node.js Python และ Go

จัดการเว็บฮุก

งาน	เอนด์พอยต์
สร้างเว็บฮุกและรับข้อมูลลับ	`POST /v1/webhooks`
เปลี่ยนที่อยู่ อีเวนต์ หรือสถานะ	`PATCH /v1/webhooks/{webhook_id}`
ส่งอีเวนต์ทดสอบ	`POST /v1/webhooks/{webhook_id}/test`
หมุนเวียนข้อมูลลับ	`POST /v1/webhooks/{webhook_id}/rotate-secret`
เปิดใช้เว็บฮุกที่หยุดชั่วคราวต่อ	`POST /v1/webhooks/{webhook_id}/resume`
ดูการส่งและการตอบกลับ	`GET /v1/webhooks/{webhook_id}/deliveries`
ส่งการส่งครั้งใดครั้งหนึ่งซ้ำ	`POST /v1/webhooks/{webhook_id}/deliveries/{delivery_id}/redeliver`

การจัดการเว็บฮุกต้องใช้คีย์ที่มีบทบาท admin และขอบเขตสิทธิ์ webhooks:manage หรือผู้ดูแลระบบในหน้าจอผู้ดูแลระบบ องค์กรหนึ่งมีเว็บฮุกได้ไม่เกิน 20 รายการ เว็บฮุกเป็นส่วนหนึ่งของแพ็กเกจขององค์กร หากแพ็กเกจไม่รวมเว็บฮุก เอนด์พอยต์เหล่านี้จะตอบกลับ 403 พร้อมรหัส webhooks.feature_disabled