API webhooks

การจัดการ webhook อยู่ที่ /api/v2/webhooks ให้ถือ URL ของ webhook และข้อมูลสำหรับ signing เป็น secret

ก่อนเริ่ม

สร้าง API key ที่มีสิทธิ์ workspace ขั้นต่ำ และกำหนด event family ที่ integration ต้องใช้

ขั้นตอน

1. เปิด Settings → Integrations
2. สร้างหรือเลือกปลายทาง webhook
3. บันทึก event ID ที่ตั้งค่าและสถานะ endpoint
4. ส่ง test request ไปยัง receiver ที่ไม่ใช่ production
5. ตรวจ response และ delivery attempt ก่อนเปิดการประมวลผล production

ทำให้ receiver เป็น idempotent เก็บ event identifier และ acknowledge หลังตรวจ payload เท่านั้น อย่าสมมติว่า event ภายในแอปทุกตัวเป็น customer webhook ที่รองรับ

ตั้งค่าและตรวจ webhook

1. สร้าง endpoint ที่รับ payload และบันทึก event identifier ก่อนส่ง success response
2. ใน Settings → Integrations สร้าง webhook โดยใส่ Name, Target hook URL, Event type และ Campaign หรือ custom interest value เมื่อมี
3. บันทึก เปิดปลายทาง และใช้ Test ยืนยัน receiver บันทึก event และ API รายงาน success: true
4. ตรวจ Webhook events ด้วย status_code, success, retry_count, will_retry และ error_message
5. ลบหรืออัปเดตปลายทางเมื่อ URL เปลี่ยน การลบไม่ลบประวัติการส่ง

ใช้ cursor pagination (limit และ starting_after) กับประวัติ ถือ retry เป็น at-least-once delivery และทำ consumer ให้ idempotent

กู้คืนเมื่อผิดพลาด

Response 4xx จาก receiver มักต้องแก้ payload หรือการยืนยันตัวตน 5xx หรือ timeout retry ได้ด้วย backoff ที่มีขอบเขต ยืนยัน attempt ถัดไปใน Webhook events และส่ง event ID กับ status ที่ลบข้อมูลสำคัญแล้ว

อ้างอิง field ของ webhook

ตรวจ delivery

หลัง Test ให้ยืนยัน receiver บันทึก event ID ส่ง success response และไม่สร้าง record ซ้ำเมื่อ retry ใน Webhook events ตรวจ status_code, success, retry_count, will_retry, error_message และ timestamp_next_retry