ภาพรวมของ Webhook

Webhook คือกลไกที่เมื่อเกิดอีเวนต์ฝั่ง ReceiptRoller เช่น「มีการซื้อสำเร็จ」หรือ「สินค้าคงคลังเปลี่ยนแปลง」ระบบจะส่งคำขอ HTTPS แบบเรียลไทม์ไปยัง URL ที่ลงทะเบียนไว้ (เซิร์ฟเวอร์ของคุณ) เมื่อเทียบกับ「polling」ที่ฝั่งแอปเรียก API เป็นระยะ Webhook มี latency ต่ำกว่า สื่อสารโดยเปล่าประโยชน์น้อยกว่า และเหมาะกับการเชื่อมต่อระบบแบบขับเคลื่อนด้วยอีเวนต์

การเลือกใช้ระหว่าง Webhook และ API (polling)

ในการใช้งานจริง การใช้ Webhook + การดึง API ซ้ำเป็นระยะ ควบคู่กันปลอดภัยที่สุด แม้ Webhook จะถูกส่งตามหลักการ แต่การตกหล่นเนื่องจากปัญหาเครือข่ายหรือฝั่งผู้รับล่มก็ไม่ได้เป็นศูนย์เสมอไป

ชนิดอีเวนต์หลัก

อีเวนต์หลักที่ถูกส่ง ณ เมษายน 2026 มีดังนี้ (แบ่งตามหมวดหมู่) รายละเอียดโปรดดูส่วน Webhook ของ API reference (Swagger)

หมวดการซื้อ・ใบเสร็จ

• receipt.issued — ออกใบเสร็จแล้ว
• receipt.voided — ยกเลิกใบเสร็จแล้ว
• receipt.refunded — ดำเนินการคืนเงินแล้ว

หมวดสินค้า・สินค้าคงคลัง

• product.created / product.updated / product.deleted
• inventory.changed — จำนวนสินค้าคงคลังเปลี่ยนแปลง
• inventory.low_stock — สินค้าคงคลังต่ำกว่าเกณฑ์

หมวดคูปอง・โฆษณา

• coupon.redeemed — มีการใช้คูปอง
• campaign.started / campaign.ended
• ad.click — มีการคลิกโฆษณา (ส่งแบบ batch รวมยอด)

หมวดลูกค้า・SNS

• customer.opted_in — ยินยอมรับการสื่อสารการตลาด
• sns.post_published — เผยแพร่โพสต์ SNS แล้ว

แต่ละอีเวนต์จะถูกสมัครรับโดยการเลือก「ชื่ออีเวนต์ที่ต้องการรับ」ตอนลงทะเบียน subscription การไม่สมัครรับอีเวนต์ที่ไม่จำเป็นจะช่วยลดภาระของฝั่งผู้รับได้

รูปแบบการส่ง

Webhook จะถูกส่งในรูปแบบต่อไปนี้

• เมธอด：HTTPS POST (ไม่รองรับ HTTP)
• Content-Type：application/json
• เนื้อหา (body)：JSON payload ที่มีข้อมูลอีเวนต์
• Header ลายเซ็น：X-RR-Signature (HMAC-SHA256)
• Event ID：X-RR-Event-Id (ใช้เป็นคีย์ idempotency)
• Timeout：ฝั่งผู้รับต้องคืน 2xx ภายใน 10 วินาที

ตัวอย่าง payload (receipt.issued)

{
  "event_id": "evt_01HV5K3M2N9PQR",
  "event_type": "receipt.issued",
  "occurred_at": "2026-04-27T10:15:23.000Z",
  "store_id": "str_abc123",
  "data": {
    "receipt_id": "rcp_xyz789",
    "total_amount": 3850,
    "currency": "JPY",
    "issued_at": "2026-04-27T10:15:22.500Z",
    "items_count": 4
  }
}

ฝั่งผู้รับจะแยกสาขาการประมวลผลด้วย event_type และใช้แต่ละฟิลด์ภายใน data เพื่ออัปเดตระบบของตน หากต้องการข้อมูลรายละเอียด ให้ใช้ receipt_id ดึงข้อมูลตัวจริงผ่าน API payload ของ Webhook จะมีเพียงข้อมูลสรุปแบบเบาเท่านั้น

แนวคิดเรื่องการรับประกันการส่ง

Webhook ของ ReceiptRoller ใช้การรับประกันการส่งแบบ at-least-once (อย่างน้อยหนึ่งครั้ง) กล่าวคือ อีเวนต์เดียวกันอาจมาถึงตั้งแต่ 2 ครั้งขึ้นไปได้ ฝั่งผู้รับจำเป็นต้องทำidempotencyโดยใช้ event_id

• บันทึก event_id ที่ประมวลผลแล้ว และเมื่อตรวจพบว่าซ้ำให้เพิกเฉย
• เขียนการประมวลผลให้เป็น idempotent (ให้ผลลัพธ์เหมือนกันแม้ใช้ข้อมูลเดียวกัน 2 ครั้ง)
• ไม่รับประกันลำดับ (อีเวนต์ที่เกิดทีหลังอาจมาถึงก่อนได้)

รายละเอียดโปรดดู การออกแบบการส่งซ้ำ ลำดับ และ idempotency

ค่าบริการและแพลน

การใช้ Webhook ไม่มีค่าบริการเพิ่มเติม สามารถใช้ได้ตั้งแต่แพลน Starter ขึ้นไป จำนวนการส่งต่อเดือนและจำนวน URL ที่เชื่อมต่อมีขีดจำกัดตามนโยบายการใช้งานที่เป็นธรรม แต่ในขอบเขตการดำเนินงานร้านค้าทั่วไปมักไม่ถึงขีดจำกัด

คู่มือที่เกี่ยวข้อง

• วิธีลงทะเบียน Webhook
• การตรวจสอบลายเซ็นและความปลอดภัย
• การออกแบบการส่งซ้ำ ลำดับ และ idempotency
• การติดตามและการรับมือเมื่อล้มเหลว
• กลับไปยังศูนย์ช่วยเหลือสำหรับนักพัฒนา