Skip to main content
หน้าหลักบล็อกคู่มือTracking Webhook Endpoint ควรส่งคืนอะไร? รหัสสถานะ การหมดเวลา และการลองใหม่?

Tracking Webhook Endpoint ควรส่งคืนอะไร? รหัสสถานะ การหมดเวลา และการลองใหม่?

17TRACK

ปลายทาง webhook สำหรับการติดตามควรส่งการตอบกลับ 2xx ที่รวดเร็วและชัดเจน หลังจากรับเหตุการณ์ไว้เพื่อประมวลผลแล้ว ในการผสานรวมส่วนใหญ่ รูปแบบที่ปลอดภัยที่สุดคือยืนยันคำขอ ตรวจสอบ payload จัดเก็บหรือเข้าคิวเหตุการณ์ และตอบรับด้วย 200 OK หรือ 202 Accepted ใช้การตอบกลับ 4xx สำหรับคำขอที่ผู้ส่งไม่ควรลองใหม่ และใช้การตอบกลับ 5xx เมื่อปัญหาชั่วคราวฝั่งเซิร์ฟเวอร์ทำให้ไม่สามารถรับเหตุการณ์ได้ ระยะหมดเวลาและพฤติกรรมการลองใหม่ที่แน่นอนยังขึ้นอยู่กับข้อตกลงของผู้ให้บริการ webhook ดังนั้นการใช้งานของคุณควรออกแบบตามพฤติกรรมของผู้ส่งที่มีการจัดทำเอกสารไว้ ไม่ใช่ตามสมมติฐาน

ปลายทาง Tracking Webhook ควรส่งรหัสสถานะและจัดการระยะหมดเวลาอย่างไร

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

ข้อตกลงการตอบกลับในทางปฏิบัติ

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

  1. รับคำขอ HTTP ผ่าน HTTPS
  2. ตรวจสอบลายเซ็น ข้อมูลรับรองการยืนยันตัวตน timestamp หรือการควบคุมความถูกต้องของคำขออื่น ๆ ที่ผู้ให้บริการกำหนด
  3. แยกวิเคราะห์และตรวจสอบ payload โดยไม่ดำเนินงาน downstream ที่ใช้เวลานาน
  4. เขียนเหตุการณ์ หรือระเบียนป้องกันข้อมูลซ้ำและข้อมูลอ้างอิงเหตุการณ์ ลงในพื้นที่จัดเก็บถาวรหรือคิวที่เชื่อถือได้
  5. ส่งการตอบกลับ 2xx ที่ตั้งใจไว้
  6. ประมวลผลการอัปเดตการติดตาม การแจ้งเตือนลูกค้า การเปลี่ยนแปลงสินค้าคงคลัง หรือการดำเนินการทางธุรกิจอื่น ๆ แบบอะซิงโครนัส

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

Webhook ควรส่งรหัสสถานะใด

การตอบกลับความหมายสำหรับผู้ส่งการใช้ทั่วไปกับ webhook
200 OKคำขอได้รับการยอมรับและจัดการสำเร็จค่าเริ่มต้นที่เหมาะสมหลังจากตรวจสอบและรับข้อมูลอย่างถาวร
202 Acceptedคำขอได้รับการยอมรับเพื่อประมวลผล แต่งานอาจดำเนินต่อไปมีประโยชน์เมื่อเหตุการณ์ถูกเข้าคิวอย่างปลอดภัย แต่การประมวลผลทางธุรกิจเป็นแบบอะซิงโครนัส
204 No Contentคำขอสำเร็จและไม่จำเป็นต้องมีเนื้อหาในการตอบกลับเหมาะสมเมื่อผู้ให้บริการยอมรับการตอบกลับสำเร็จที่ไม่มีเนื้อหา
400–499คำขอไม่ถูกต้อง ไม่ได้รับอนุญาต หรือไม่สามารถยอมรับได้ตามที่ส่งมาPayload ผิดรูปแบบ การยืนยันตัวตนล้มเหลว ลายเซ็นไม่ถูกต้อง หรือเหตุการณ์ที่ถูกปฏิเสธอย่างถาวร
429 Too Many Requestsผู้รับกำลังจำกัดอัตราการรับคำขอใช้เฉพาะเมื่อพฤติกรรมการลองใหม่ของผู้ส่งและนโยบายจำกัดอัตราของคุณสอดคล้องกัน
500–599ผู้รับไม่สามารถรับคำขอได้เนื่องจากปัญหาฝั่งเซิร์ฟเวอร์หรือปัญหาชั่วคราวฐานข้อมูลขัดข้อง คิวล้มเหลว ความล้มเหลวของ dependency หรือข้อผิดพลาดของแอปพลิเคชันที่ไม่คาดคิด

200 OK มักเป็นตัวเลือกที่สร้างความประหลาดใจน้อยที่สุด เพราะเข้าใจกันอย่างกว้างขวางว่าเป็นการรับข้อมูลสำเร็จ 202 Accepted ก็มีความหมายที่เหมาะสมเมื่อปลายทางรับเหตุการณ์ไว้เพื่อประมวลผลภายหลัง อย่างไรก็ตาม ไม่มีรหัสใดถูกต้องโดยอัตโนมัติ เอกสารของผู้ส่งอาจกำหนดว่าการตอบกลับ 2xx ใดถือว่าสำเร็จ และผู้ให้บริการบางรายอาจคาดหวัง body หรือ content type ที่เฉพาะเจาะจง

อย่าส่งการตอบกลับ 2xx เพียงเพราะคำขอ HTTP มาถึงเซิร์ฟเวอร์ของคุณ หากการตรวจสอบลายเซ็นล้มเหลวหรือไม่สามารถตีความ payload ได้อย่างปลอดภัย โดยทั่วไปการตอบกลับ 4xx จะตรงตามความเป็นจริงมากกว่า ในทางกลับกัน อย่าส่ง 4xx เมื่อฐานข้อมูลขัดข้องชั่วคราว หากเหตุการณ์อาจสำเร็จได้ในภายหลัง การตอบกลับ 5xx เปิดโอกาสให้ผู้ส่งที่รองรับการลองใหม่ส่งเหตุการณ์อีกครั้ง แม้ว่าผู้ให้บริการอาจใช้นโยบายของตนเอง

ควรจัดการระยะหมดเวลาอย่างไร

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

ข้อผิดพลาดด้านการออกแบบที่พบบ่อยที่สุดคือดำเนินงาน downstream ทั้งหมดก่อนตอบรับ webhook ตัวจัดการอาจเรียกฐานข้อมูล ระบบจัดการคำสั่งซื้อ บริการแจ้งเตือน และกระบวนการวิเคราะห์ตามลำดับ dependency ที่ช้าตัวเดียวอาจทำให้ผู้ส่งพบการหมดเวลา แม้แอปพลิเคชันของคุณจะดำเนินงานเสร็จในภายหลัง จากนั้นผู้ส่งอาจลองใหม่ ทำให้เกิดการประมวลผลซ้ำหรือการอัปเดตที่ขัดแย้งกัน

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

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

อะไรเป็นสาเหตุให้เกิดการลองใหม่

ผู้ส่ง webhook อาจลองใหม่หลังจากเกิดข้อผิดพลาดในการเชื่อมต่อ การหมดเวลา หรือได้รับการตอบกลับที่ข้อตกลงของผู้ส่งจัดประเภทว่าไม่สำเร็จ กำหนดการที่แน่นอน จำนวนครั้งสูงสุด อัลกอริทึม backoff และช่วงเวลาการส่งแตกต่างกันไปตามผู้ให้บริการ อย่ารับประกันจำนวนครั้งการลองใหม่ที่ตายตัว เว้นแต่จะระบุไว้ในเอกสารของผู้ให้บริการ

ผู้รับควรสมมติว่าการลองใหม่สามารถเกิดขึ้นได้ และออกแบบรองรับอย่างตั้งใจ:

  • ใช้ตัวระบุเหตุการณ์เมื่อมี จัดเก็บพร้อมข้อจำกัด unique หรือคีย์ป้องกันข้อมูลซ้ำที่เทียบเท่า
  • ทำให้การประมวลผลเป็น idempotent การใช้การอัปเดตสถานะการจัดส่งเดียวกันสองครั้งไม่ควรส่งข้อความลูกค้าสองครั้ง สร้างการคืนเงินสองครั้ง หรือเลื่อนสถานะคำสั่งซื้อผิดพลาด
  • เก็บ payload เดิมหรือระเบียนตรวจสอบที่มีประโยชน์ เพื่อรองรับการเล่นซ้ำ การตรวจสอบ และการกระทบยอด
  • แยกการรับข้อมูลออกจากการประมวลผล worker สามารถลองใหม่เมื่อเกิดความล้มเหลวภายในโดยไม่บังคับให้ผู้ส่งทำ HTTP exchange ทั้งหมดซ้ำ
  • บันทึกรหัสตอบกลับและเวลาแฝง การเพิ่มขึ้นของการตอบกลับ 5xx การหมดเวลา หรือ ID เหตุการณ์ซ้ำ อาจเผยให้เห็นการขัดข้องก่อนที่ผู้ใช้จะรายงานว่าการอัปเดตการติดตามหายไป

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

ควรส่ง 4xx, 429 หรือ 5xx เมื่อใด

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

ใช้ 429 อย่างระมัดระวัง HTTP กำหนด 429 สำหรับการจำกัดอัตรา และ header Retry-After สามารถสื่อสารได้ว่าควรลองใหม่เมื่อใด อย่างไรก็ตาม ผู้ส่ง webhook ทุกระบบไม่ได้ตีความ 429 แบบเดียวกัน หากคิวเต็มหรือบริการของคุณมีภาระงานสูง ให้ยืนยันว่าผู้ให้บริการจะลองใหม่อย่างปลอดภัย และกำหนดการลองใหม่จะไม่ทำให้ภาระงานสูงขึ้น โดยทั่วไปคิวรับข้อมูลที่มีขอบเขตและแผน backpressure ดีกว่าการปล่อยให้คำขอล้มเหลวอย่างคาดเดาไม่ได้

ส่ง 5xx เมื่อผู้รับไม่สามารถรับเหตุการณ์ได้อย่างปลอดภัยเนื่องจากปัญหาชั่วคราว ซึ่งรวมถึงฐานข้อมูลไม่พร้อมใช้งาน การเขียนคิวถาวรล้มเหลว หรือข้อผิดพลาดภายในที่ทำให้การตรวจสอบหรือการบันทึกถาวรไม่สำเร็จ การส่ง 200 ทั้งที่ทิ้งเหตุการณ์ไปโดยเงียบ ๆ จะทำให้กู้คืนได้ยากขึ้น เพราะผู้ส่งไม่มีเหตุผลที่จะลองใหม่

หลีกเลี่ยงการพึ่งพาการ redirect เช่น 301, 302 หรือ 307 สำหรับการส่ง webhook การจัดการ redirect แตกต่างกันระหว่างไคลเอ็นต์ และการ redirect คำขอที่ลงลายเซ็นอาจทำให้ปลายทาง method และ body ไม่ชัดเจน ให้กำหนดค่าผู้ให้บริการด้วยปลายทาง HTTPS สุดท้ายแทน

นโยบายการตอบกลับที่เชื่อถือได้สำหรับเหตุการณ์การติดตาม

สำหรับการผสานรวม tracking webhook ส่วนใหญ่ นโยบายต่อไปนี้เป็นจุดเริ่มต้นที่เหมาะสม:

  1. ส่ง 200 หรือ 202 หลังจากเหตุการณ์ผ่านการยืนยันตัวตนและถูกจัดเก็บถาวรหรือใส่ไว้ในคิวที่เชื่อถือได้
  2. ส่งการตอบกลับ 4xx สำหรับลายเซ็นไม่ถูกต้อง การยืนยันตัวตนไม่ถูกต้อง หรือ payload ที่ใช้งานไม่ได้อย่างถาวร โดยปฏิบัติตามกฎที่ผู้ให้บริการจัดทำเอกสารไว้
  3. ส่ง 5xx เมื่อความล้มเหลวชั่วคราวขัดขวางการรับข้อมูลอย่างถาวร
  4. ส่งการตอบกลับสำเร็จสำหรับข้อมูลซ้ำที่ระบุได้อย่างปลอดภัย พร้อมป้องกันผลกระทบทางธุรกิจซ้ำ
  5. ทำให้ตัวจัดการทำงานรวดเร็วและวัดเวลาแฝงในการตอบรับ
  6. ทดสอบสถานการณ์หมดเวลา ลองใหม่ ซ้ำ ลำดับไม่ถูกต้อง รูปแบบผิด และผู้ให้บริการขัดข้องก่อนเปิดใช้งานจริง

หากคุณกำลังผสานรวม tracking API ให้เริ่มจากเอกสาร webhook ของผู้ให้บริการ และยืนยันรหัสความสำเร็จที่ยอมรับ วิธีลงลายเซ็นคำขอ ระยะหมดเวลา เงื่อนไขการลองใหม่ schema ของ payload และตัวระบุเหตุการณ์ สำหรับการผสานรวม 17TRACK ให้ตรวจสอบ เอกสาร Tracking API อย่างเป็นทางการ ซึ่งเป็นแหล่งที่เหมาะสมในการตรวจสอบข้อตกลงเฉพาะของผู้ให้บริการ แทนการอนุมานจากแนวปฏิบัติ HTTP ทั่วไป

รายการตรวจสอบการใช้งาน

  • ปลายทางเข้าถึงได้ผ่าน HTTPS และมี URL สำหรับ production ที่คงที่
  • การยืนยันตัวตนและการตรวจสอบลายเซ็นเกิดขึ้นก่อนการประมวลผลทางธุรกิจ
  • คำขอดิบหรือรูปแบบที่ตรวจสอบยืนยันได้ถูกเก็บไว้ตามความจำเป็นสำหรับการตรวจสอบลายเซ็นและการแก้ไขปัญหา
  • เหตุการณ์ถูกบันทึกถาวรก่อนส่งการตอบกลับสำเร็จ
  • การส่งซ้ำปลอดภัยและไม่ทำให้เกิดการดำเนินการที่ย้อนกลับไม่ได้ซ้ำ
  • Worker สามารถลองประมวลผลภายในใหม่ได้โดยไม่ขึ้นกับรอบการลองใหม่ HTTP ของผู้ส่ง
  • บันทึกประกอบด้วย ID เหตุการณ์ เวลาส่ง รหัสตอบกลับ สถานะการประมวลผล และ correlation ID โดยไม่เปิดเผยข้อมูลลับ
  • การแจ้งเตือนแยกความแตกต่างระหว่างการหมดเวลาของปลายทาง ความล้มเหลวในการตรวจสอบ 4xx การขัดข้อง 5xx ความล่าช้าของคิว และการส่งซ้ำ
  • พฤติกรรมของผู้ให้บริการที่ระบุไว้ในเอกสารได้รับการทดสอบด้วยเหตุการณ์จริงหรือ sandbox แล้ว

คำถามที่พบบ่อย

200 OK ดีกว่า 202 Accepted สำหรับ webhook หรือไม่

ไม่มีแบบใดดีกว่าเสมอไป ใช้ 200 OK เมื่อคำขอได้รับการยอมรับและการผสานรวมของคุณถือว่าการตอบกลับเป็นความสำเร็จทั่วไป ใช้ 202 Accepted เมื่อเหตุการณ์ได้รับการยอมรับเพื่อประมวลผลแบบอะซิงโครนัส ยืนยันว่าผู้ส่งจัดประเภทการตอบกลับ 2xx ที่เลือกว่าสำเร็จ

ปลายทาง webhook ควรรอจนกว่าการอัปเดตการติดตามจะประมวลผลเสร็จสมบูรณ์หรือไม่

โดยทั่วไปไม่ควร ควรรอเฉพาะจนกว่าเหตุการณ์จะได้รับการยืนยันตัวตน ตรวจสอบ และรับไว้อย่างถาวร งานที่ใช้เวลานานควรดำเนินการหลังการตอบรับ เพื่อไม่ให้ dependency ที่ช้าทำให้เกิดการหมดเวลาและการลองใหม่โดยไม่จำเป็น

ควรทำอย่างไรเมื่อเหตุการณ์การติดตามเดียวกันมาถึงสองครั้ง

ระบุเหตุการณ์ด้วย event ID ของผู้ให้บริการหรือคีย์ที่เทียบเท่าซึ่งออกแบบอย่างรอบคอบ ข้ามผลกระทบข้างเคียงที่ซ้ำ และส่งการตอบกลับสำเร็จหากเหตุการณ์นั้นถูกรับไว้แล้ว วิธีนี้ทำให้การลองใหม่ปลอดภัยโดยไม่ซ่อนความล้มเหลวในการประมวลผลครั้งใหม่

ลายเซ็นไม่ถูกต้องควรส่ง 400 หรือ 401

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

การตอบกลับ 5xx ทำให้เกิดการลองใหม่เสมอหรือไม่

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

แหล่งข้อมูล

  • RFC 9110: HTTP Semantics — คำจำกัดความสำหรับความสำเร็จ ข้อผิดพลาดฝั่งไคลเอ็นต์ ข้อผิดพลาดฝั่งเซิร์ฟเวอร์ การเปลี่ยนเส้นทาง และการจัดการการตอบกลับ
  • RFC 6585: Additional HTTP Status Codes — ข้อกำหนดสำหรับ 429 Too Many Requests
  • Stripe Webhooks Documentation — แนวทางเชิงปฏิบัติเกี่ยวกับการตอบกลับ webhook การประมวลผลแบบอะซิงโครนัส และการจัดการเหตุการณ์ซ้ำ
  • GitHub Docs: Handling Webhook Deliveries — การตรวจสอบการส่งและข้อควรพิจารณาด้านการปฏิบัติการสำหรับการผสานรวม webhook
  • 17TRACK Tracking API Documentation — เอกสารเฉพาะของผู้ให้บริการที่ควรตรวจสอบเมื่อใช้งานการผสานรวม tracking API