Webhook เป็นการแจ้งเตือนความเคลื่อนไหวจากเซิร์ฟเวอร์ของเราไปยัง HTTPS endpoint ที่คุณกำหนดเมื่อเกิด Event บางอย่างขึ้นในบัญชี ซึ่งการแจ้งเตือนเหล่านี้จะส่ง ออบเจ็กต์ event ที่มีข้อมูลเกี่ยวกับเหตุการณ์ที่ทริกเกอร์ไปยัง endpoint URL ที่คุณกำหนด การใช้ Webhook ช่วยให้คุณได้รับการแจ้งเตือนเกี่ยวกับเหตุการณ์ที่สำคัญในบัญชี (เช่น การรับชำระเงินสำเร็จ) ได้
คุณสามารถใช้ URL ที่แตกต่างกันได้สำหรับโหมดทดสอบและโหมดใช้งานจริง โดยคุณสามารถเพิ่มหรืออัปเดต endpoint ของโหมดทดสอบได้โดยไปที่ https://dashboard.omise.co/test/webhooks ดูข้อมูลทั้งหมดเกี่ยวกับ event ได้ที่แดชบอร์ดในหน้า Events หรือที่ Events API
การประมวลผลเป็นลำดับ (Serialization)
ออบเจ็กต์ event ในคำขอ POST (หรือการตอบกลับผ่าน Events API) จะประมวลผลตามลำดับตาม API Version เริ่มต้นของ Event เสมอและไม่เกี่ยวข้องกับค่า Omise-Version ที่ส่งไปใน Event ที่ทริกเกอร์ ดังนั้น หากบัญชีตั้งค่าเวอร์ชันไว้ที่ 2017-11-02 รายการรับชำระเงินที่สร้างขึ้นโดยใช้ curl ที่ส่งข้อมูลเวอร์ชันเป็น -H "Omise-Version: 2019-05-29" จะสร้าง Event (charge.create) ที่มีออบเจ็กต์ charge ซึ่งเรียงลำดับตามเวอร์ชัน 2017-11-02 ของ Charge API ไม่ใช่เวอร์ชัน 2019-05-29 เมื่ออัปเดตเป็นเวอร์ชัน 2019-05-29 ในภายหลัง ออบเจ็กต์ charge สำหรับ event นี้จะยังคงเรียงลำดับตามเวอร์ชัน 2017-11-02
ข้อกำหนดและแนวทางปฏิบัติ
URL ต้องเป็น HTTPS และต้องมีใบรับรอง SSL ที่ใช้งานได้ ไม่ใช่ใบรับรองที่สร้างขึ้นเอง (self-signed certificate) คุณสามารถรับใบรับรอง SSL สำหรับ endpoint ได้ที่ letsencrypt.org โดยไม่มีค่าใช้จ่ายและยืนยันใบรับรองดังกล่าวได้โดยใช้ SSL test
เราขอแนะนำให้ร้านค้ายืนยันความถูกต้องของ event บน webhook ที่ได้รับเพื่อตรวจสอบว่าการแจ้งเตือนดังกล่าวเป็นการแจ้งเตือนจริง เช่น หากคุณได้รับ Event charge.complete จาก Webhook ให้ใช้ Charge ID เพื่อสร้างคำขอ GET สำหรับรายการรับชำระเงินดังกล่าว (เช่น /charges/chrg_test_no1t4tnemucod0e51mo) เพื่อยืนยัน status จากอีกช่องทางหนึ่ง
Event ต่างๆ ที่มีการแจ้งเตือน
Event เกี่ยวกับบัตร
| ชื่อ Event |
ทริกเกอร์ |
card.destroy |
อัปเดตบัตรแล้ว |
card.update |
ทำลายบัตรแล้ว |
Event เกี่ยวกับรายการรับชำระเงิน
| ชื่อ Event |
ทริกเกอร์ |
charge.capture |
ตัดวงเงินแล้ว (สำหรับการตัดวงเงินด้วยตัวเอง (Manual Capture) เท่านั้น) |
charge.complete |
รับชำระเงินสำเร็จ (หมายเหตุ: รายการรับชำระเงินผ่านบัตรที่ไม่ผ่าน 3DS จะไม่ทริกเกอร์ Event นี้) |
charge.create |
สร้างรายการรับชำระเงินแล้ว |
charge.expire |
รายการรับชำระเงินหมดอายุ (สำหรับ อาลีเพย์ (บาร์โค้ด) เท่านั้น) |
charge.reverse |
ยกเลิกการกันวงเงิน (สำหรับการยกเลิกการกันวงเงินด้วยตนเองเท่านั้น) |
charge.update |
อัปเดตรายการรับชำระเงินแล้ว |
Event เกี่ยวกับลูกค้า
| ชื่อ Event |
ทริกเกอร์ |
customer.create |
สร้างลูกค้าแล้วd |
customer.destroy |
ลบลูกค้าแล้ว |
customer.update |
อัปเดตลูกค้าแล้ว |
customer.update.card |
อัปเดตบัตรแล้ว (การอัปเดตผ่านทางลูกค้า) |
Event เกี่ยวกับการปฏิเสธรายการ
| ชื่อ Event |
ทริกเกอร์ |
dispute.accept |
รับการปฏิเสธรายการแล้ว |
dispute.close |
ยุติการปฏิเสธรายการแล้ว |
dispute.create |
สร้างการปฏิเสธรายการแล้ว |
dispute.update |
อัปเดตการปฏิเสธรายการแล้ว |
Event เกี่ยวกับลิงก์
| ชื่อ Event |
ทริกเกอร์ |
link.create |
สร้างลิงก์แล้ว |
Event เกี่ยวกับผู้รับโอน
| ชื่อ Event |
ทริกเกอร์ |
recipient.activate |
เปิดใช้งานผู้รับโอนแล้ว |
recipient.create |
สร้างผู้รับโอนแล้ว |
recipient.deactivate |
ปิดใช้งานผู้รับโอนแล้ว |
recipient.destroy |
ลบผู้รับโอนแล้ว |
recipient.update |
อัปเดตผู้รับโอนแล้ว |
recipient.verify |
ยืนยันผู้รับโอนแล้ว |
Event เกี่ยวกับการคืนเงิน
| ชื่อ Event |
ทริกเกอร์ |
refund.create |
สร้างรายการคืนเงินแล้ว |
Event เกี่ยวกับการตั้งรายการล่วงหน้า
| ชื่อ Event |
ทริกเกอร์ |
schedule.create |
สร้างการตั้งรายการล่วงหน้าแล้ว |
schedule.destroy |
ลบการตั้งรายการล่วงหน้าแล้ว |
schedule.expire |
การตั้งรายการล่วงหน้าหมดอายุแล้ว |
schedule.expiring |
การตั้งรายการล่วงหน้าจะหยดอายุเร็วๆ นี้ |
schedule.suspend |
ระงับการตั้งรายการล่วงหน้าแล้ว |
Event เกี่ยวกับรายการโอนเงิน
| ชื่อ Event |
ทริกเกอร์ |
transfer.create |
สร้างรายการโอนเงินแล้ว |
transfer.destroy |
ลบรายการโอนเงินแล้ว |
transfer.fail |
รายการโอนเงินถูกทำเครื่องหมายว่าล้มเหลว |
transfer.pay |
รายการโอนเงินถูกทำเครื่องหมายว่าจ่ายแล้ว |
transfer.send |
รายการโอนเงินถูกทำเครื่องหมายว่าส่งแล้ว |
transfer.update |
อัปเดตรายการโอนเงินแล้ว |
Webhooks แบบ Dynamic
ก่อนหน้านี้ บัญชีผู้ใช้ของ Opn Payments จะใช้ webhook แบบ static ที่สามารถกำหนดค่าเองได้ โดยการแจ้งเตือน events ทั้งหมดจะถูกส่งไปที่ endpoint ของ webhook นี้เท่านั้น
Webhook แบบ dynamic เป็นฟีเจอร์ที่ช่วยให้ร้านค้าสามารถส่งพารามิเตอร์ webhook_endpoints ขณะที่สร้างรายการชำระเงินได้ โดย event ที่เกี่ยวข้องกับรายการชำระเงินจะถูกส่งไปที่ webhook_endpoints ที่กำหนดไว้
เมื่อร้านค้าส่งพารามิเตอร์ webhook_endpoints การแจ้งเตือน event ทั้งหมดที่เกี่ยวข้องกับรายการชำระเงินที่ระบุจะถูกส่งไปที่ webhook_endpoints และจะไม่ส่งไปที่ webhook แบบ static
ในกรณีที่ร้านค้าไม่ได้ระบุพารามิเตอร์ webhook_endpoints ไว้ตอนสร้างรายการชำระเงิน ระบบจะส่งแจ้งเตือน event ไปยัง static webhook ของบัญชีแทน
