Webhook รับชำระเงินคริปโต: วิธีตรวจสอบ signature และรับมือการส่งซ้ำ

webhook คือคำขอที่ CryBit ส่งมายังเซิร์ฟเวอร์ของคุณเมื่อสถานะใบแจ้งหนี้เปลี่ยนไป เป็นวิธีที่น่าเชื่อถือที่สุดในการรู้ว่าออเดอร์ถูกชำระแล้ว แต่ในขณะเดียวกันมันก็เป็น URL สาธารณะที่ใครก็สามารถส่งคำขอเข้ามาได้ ดังนั้นต้องตรวจสอบทุกคำขอก่อนที่จะนำไปใช้งานจริงเสมอ

สิ่งที่คุณจะได้รับ

คำขอที่ส่งมาเป็น POST พร้อมบอดี้แบบ JSON ชื่ออีเวนต์จะมาในเฮดเดอร์ X-CryBit-Event เช่น payment.paid คุณเลือกได้เองว่าต้องการรับอีเวนต์ไหนบ้างในหน้าตั้งค่าร้านค้า ได้แก่ paid, expired, refunded, cancelled ส่วน URL ของ webhook จะตั้งไว้ที่ระดับร้านค้า ไม่ใช่ในคำขอสร้างใบแจ้งหนี้

ตรวจสอบ signature

ทุก webhook จะมีเฮดเดอร์ X-CryBit-Signature ในรูปแบบ t=<unix time>,v1=<hex> วิธีตรวจสอบคือนำค่า t มาต่อด้วยจุดแล้วตามด้วยบอดี้คำขอแบบดิบ (raw body) จากนั้นคำนวณ HMAC-SHA256 ด้วยคีย์ลับสำหรับเซ็นชื่อของคุณ แล้วนำผลลัพธ์ไปเทียบกับค่า v1 โดยควรเปรียบเทียบแบบ constant-time และปฏิเสธคำขอหาก t เก่ากว่าห้านาที คีย์ลับสำหรับเซ็นชื่อของแต่ละร้านค้าอยู่ในหน้าตั้งค่าร้านค้า แท็บ Integration หากไม่มีคีย์นี้จะไม่มีใครปลอมสถานะ paid ได้เลย

คำนวณลายเซ็นจากบอดี้ดิบตามที่ได้รับมาเป๊ะ ๆ หากคุณแปลง JSON ออกมาแล้วสร้างใหม่ก่อน ไบต์ของข้อมูลจะเปลี่ยนไปและการตรวจสอบจะไม่ผ่าน

ตอบกลับให้เร็ว ประมวลผลให้ปลอดภัย

• ตอบกลับด้วยสถานะ 2xx ทันทีที่บันทึกอีเวนต์เรียบร้อยแล้ว ส่วนงานที่หนักให้ไปทำภายหลัง เพราะ CryBit จะรอผลตอบกลับประมาณสิบสองวินาที
• หากไม่มีการตอบกลับ CryBit จะส่งซ้ำโดยเว้นระยะห่างที่เพิ่มขึ้นเรื่อย ๆ คือ 15 วินาที 1 นาที 5, 15 และ 30 นาที จากนั้น 2, 6 และ 24 ชั่วโมง หากตอบกลับด้วยสถานะ 4xx ที่ไม่ใช่ 429 การส่งซ้ำจะหยุดทันที
• ทำให้การประมวลผลเป็นแบบ idempotent เพราะอีเวนต์เดียวกันอาจถูกส่งมาซ้ำได้มากกว่าหนึ่งครั้ง ให้ใช้ order_id หรือ uuid ของใบแจ้งหนี้เป็นคีย์ และมองข้ามการส่งซ้ำครั้งถัดไป
• อย่าปิดออเดอร์โดยอาศัยเพียงอีเวนต์จากวิดเจ็ตในเบราว์เซอร์ เพราะอีเวนต์นั้นมีไว้สำหรับหน้าตาอินเทอร์เฟซของผู้ใช้เท่านั้น

หากด้วยเหตุใดก็ตามที่คุณพลาด webhook ไป ให้เรียกดูสถานะใบแจ้งหนี้ด้วย GET /api/v1/payments/{uuid} เพราะสถานะนี้คือแหล่งข้อมูลที่ถูกต้องที่สุดเสมอ