ในการทดสอบ webhook คุณจะต้องให้ URL ที่เข้าถึงได้แก่ผู้ให้บริการ เรียกใช้เหตุการณ์จริง จากนั้นยืนยันว่า handler ของคุณยอมรับ payload และตอบสนองได้อย่างถูกต้อง ส่วนที่ยากคือแอปของคุณเป็นผู้รับ ไม่ใช่ผู้เรียก ดังนั้นคุณจึงไม่สามารถเพียงแค่กด "ส่ง" และอ่านการตอบกลับได้ คู่มือนี้จะแนะนำเครื่องมือที่คุณต้องการ (บริการตรวจสอบ, local tunnels, provider triggers) และกระบวนการที่ทำซ้ำได้เพื่อยืนยัน handler ของคุณตั้งแต่ต้นจนจบ
เหตุใด webhook จึงทดสอบยากกว่า API ทั่วไป
ในการเรียกใช้ API ทั่วไป คุณสามารถควบคุม request ได้ คุณเลือกเมธอด กำหนด body ส่ง request และอ่าน response Webhooks จะกลับกัน ผู้ให้บริการจะส่ง request มาให้คุณ ตามกำหนดเวลาของมันเอง พร้อมกับ payload ที่กำหนดเอง การสลับบทบาทนี้ทำให้เกิดปัญหาในการทดสอบสี่ประการ
ประการแรก โดยค่าเริ่มต้น คุณไม่สามารถเรียกใช้เหตุการณ์ได้เอง เหตุการณ์ payment_intent.succeeded จะเกิดขึ้นก็ต่อเมื่อ Stripe ตัดสินใจว่าเกิดขึ้นแล้ว ดังนั้นคุณจึงต้องใช้เครื่องมือของผู้ให้บริการเพื่อบังคับให้เกิดเหตุการณ์นั้น
ประการที่สอง การส่งเป็นแบบอะซิงโครนัส เหตุการณ์จะมาถึงเมื่อการดำเนินการต้นน้ำเสร็จสมบูรณ์ ดังนั้นการทดสอบของคุณจะต้องจับ request ที่เข้ามา แทนที่จะรอค่าที่ส่งกลับมา
ประการที่สาม รูปแบบ payload ถูกกำหนดโดยผู้ให้บริการ handler ของคุณจะต้องแยกวิเคราะห์สิ่งที่ GitHub, Stripe หรือ Slack ส่งมาให้ได้อย่างถูกต้อง
ประการที่สี่ ผู้ให้บริการส่วนใหญ่จะเซ็นชื่อ request ของพวกเขา Endpoint ของคุณจะต้องตรวจสอบ signature header ก่อนที่จะเชื่อถือ body และการทดสอบที่ข้ามขั้นตอนนี้จะซ่อนข้อบกพร่องที่แท้จริง สำหรับข้อมูลเชิงลึกเพิ่มเติม โปรดดูคู่มือของเราเกี่ยวกับการ ตรวจสอบลายเซ็น webhook
หากคุณยังคงตัดสินใจอยู่ว่า webhook เป็นรูปแบบที่เหมาะสมสำหรับการรวมระบบของคุณหรือไม่ การเปรียบเทียบ webhooks vs polling และ webhook vs WebSocket จะช่วยให้คุณเห็นข้อดีข้อเสีย
ชุดเครื่องมือทดสอบ webhook
คุณจะต้องใช้เครื่องมือสี่ประเภท ซึ่งมักจะใช้ในการทำงานครั้งเดียวกัน: บริการจับภาพ (capture service) เพื่อดู raw payloads, ทันเนล (tunnel) เพื่อเชื่อมต่อกับแล็ปท็อปของคุณ, provider triggers เพื่อเรียกใช้เหตุการณ์จริง และเครื่องมือยืนยัน (assertion tool) เพื่อตรวจสอบ handler ของคุณ
1. บริการตรวจสอบและจับภาพ
ก่อนที่คุณจะเขียนโค้ด handler แม้แต่บรรทัดเดียว ให้ชี้ผู้ให้บริการไปยัง URL ชั่วคราว (throwaway URL) และดูว่ามันส่งอะไรมาจริง ๆ บริการเหล่านี้จะให้ endpoint สาธารณะแก่คุณและแสดง request ทุกรายการแบบเรียลไทม์
webhook.site จะให้ URL และที่อยู่อีเมลแบบสุ่มที่ไม่ซ้ำกันแก่คุณทันทีที่หน้าเว็บโหลด ทุกสิ่งที่ส่งไปยังที่อยู่นั้นจะปรากฏขึ้นทันที: full body, headers และ method ฟรี URL จะหมดอายุหลังจาก 7 วันและจำกัดที่ 100 requests โดยมีขนาด request สูงสุด 10 MB แผนแบบชำระเงินจะเพิ่ม URL ถาวร, requests ไม่จำกัด และประวัติการจัดเก็บ 10,000 requests ล่าสุด
Beeceptor มี HTTPS endpoint ฟรีที่คุณสามารถใช้เป็นตัวรับ webhook และตรวจสอบ incoming payloads ได้แบบเรียลไทม์ นอกจากนี้ยังมี mock-server endpoints เพื่อให้คุณสามารถจับภาพและจำลองได้จากเครื่องมือเดียวกัน
Pipedream RequestBin เป็นเครื่องมือจับ request ที่นิยมใช้อีกตัวหนึ่ง ตรวจสอบเอกสารปัจจุบันของมันสำหรับรายละเอียดระดับชั้น (tier specifics) เนื่องจากบริการจับภาพมักจะเปลี่ยนขีดจำกัดฟรีบ่อยครั้ง
ใช้สิ่งเหล่านี้เพื่อตอบคำถามเดียว: payload จริงมีลักษณะอย่างไร? คัดลอกตัวอย่างไว้ใช้ภายหลัง เมื่อคุณสร้างการทดสอบที่ทำซ้ำได้
2. การพัฒนาในเครื่อง: เปิดเผย localhost ด้วยทันเนล
ผู้ให้บริการไม่สามารถเข้าถึง localhost:3000 บนเครื่องของคุณได้ ทันเนลจะสร้าง URL สาธารณะแบบ HTTPS ที่ส่งต่อทราฟฟิกไปยังพอร์ตในเครื่องของคุณ เพื่อให้คุณสามารถรัน handler ใน editor และดีบักแบบสดได้
ngrok เป็นตัวเลือกที่นิยม ติดตั้ง, ยืนยันตัวตนครั้งเดียว จากนั้นส่งต่อพอร์ต
brew install ngrok # macOS
ngrok config add-authtoken $YOUR_TOKEN
ngrok http 3000 # ส่งต่อ URL สาธารณะแบบ HTTPS ไปยัง localhost:3000
บัญชี ngrok แบบฟรีจะได้รับโดเมน dev ที่เลือกโดยอัตโนมัติ โดเมนที่กำหนดเองต้องใช้แผนแบบชำระเงิน
cloudflared จะรัน quick tunnel ด้วยคำสั่งเดียว หากคุณชอบ Cloudflare
cloudflared tunnel --url http://localhost:3000
คัดลอก URL สาธารณะที่ทันเนลแสดง ไปวางในการตั้งค่า webhook ของผู้ให้บริการ และเหตุการณ์ที่เข้ามาจะมาถึงเซิร์ฟเวอร์ในเครื่องของคุณ สำหรับคำแนะนำฉบับเต็มเกี่ยวกับรูปแบบนี้ โปรดดูที่ วิธีการทดสอบ localhost APIs ด้วยบริการ webhook
3. การเรียกใช้เหตุการณ์ทดสอบจากผู้ให้บริการ
URL สำหรับจับภาพจะมีประโยชน์ก็ต่อเมื่อมีบางสิ่งถูกส่งไปยังมันแล้ว ผู้ให้บริการรายใหญ่ส่วนใหญ่มีเครื่องมือสำหรับเรียกใช้เหตุการณ์ทดสอบตามความต้องการ ดังนั้นคุณจึงไม่จำเป็นต้องสร้างการชำระเงินหรือการพุชจริง ๆ
Stripe CLI เป็นตัวอย่างที่ชัดเจนที่สุด คำสั่ง stripe listen จะส่งต่อเหตุการณ์สดจาก Stripe sandbox ของคุณไปยัง local path และจะแสดง webhook signing secret ที่คุณนำไปใส่ในการกำหนดค่าแอปของคุณ
# ส่งต่อเหตุการณ์ทั้งหมดไปยัง handler ในเครื่องของคุณ:
stripe listen --forward-to localhost:3000/webhooks
# กรองเฉพาะเหตุการณ์ที่ต้องการเท่านั้น:
stripe listen --events payment_intent.succeeded,checkout.session.completed \
--forward-to localhost:3000/webhooks
เมื่อ listener ทำงานอยู่ stripe trigger จะเรียกใช้เหตุการณ์ทดสอบ โปรดทราบว่าการเรียกใช้จะสร้าง API objects ที่มีข้อมูลรองรับอย่างถูกต้องและมีผลข้างเคียง: payment_intent.succeeded ยังปล่อย payment_intent.created ออกมาด้วย
stripe trigger payment_intent.succeeded
stripe trigger checkout.session.completed
stripe trigger --help # แสดงรายการเหตุการณ์ที่รองรับทั้งหมด
GitHub เก็บประวัติการส่งมอบสั้นๆ ที่คุณสามารถเล่นซ้ำได้ ไปที่ repo ของคุณ จากนั้น Settings, แล้ว Webhooks ภายใต้ "Code and automation" คลิกที่ URL ของ webhook, เปิดแท็บ "Recent deliveries", คลิก GUID ของการส่งมอบ และคลิก "Redeliver" มีข้อจำกัดสองประการที่สำคัญ: คุณสามารถ redeliver ได้เฉพาะการส่งมอบจาก 3 วันที่ผ่านมาเท่านั้น และคุณต้องมีสิทธิ์เข้าถึงแบบ admin ใน repo GitHub จะไม่ redeliver การส่งมอบที่ล้มเหลวโดยอัตโนมัติ ดังนั้นการเล่นซ้ำจึงต้องทำด้วยตนเอง
Slack incoming webhooks นั้นง่ายที่สุดในการทดสอบ คุณส่งข้อความโดยการ POST JSON ไปยัง URL ของ webhook payload ขั้นต่ำคือเพียงแค่ฟิลด์ text
curl -X POST https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX \
-H 'Content-type: application/json' \
-d '{"text":"Hello, world."}'
URL ของ Slack webhook เป็นความลับ Slack จะเพิกถอน URL ที่รั่วไหล ดังนั้นควรเก็บไว้ให้ห่างจากโค้ดฝั่งไคลเอ็นต์และ public repos
4. การยืนยัน handler ของคุณ
การจับภาพและการเรียกใช้พิสูจน์ว่าระบบทำงานได้ แต่ไม่ได้พิสูจน์ว่า handler ของคุณถูกต้อง เครื่องมือสุดท้ายจะส่ง payload ที่สร้างขึ้น และตรวจสอบ response รวมถึงผลข้างเคียง ที่พื้นฐานที่สุด นั่นคือคำสั่ง curl ที่มี body ที่เป็นตัวแทน
curl -X POST http://localhost:3000/webhooks \
-H 'Content-Type: application/json' \
-H 'Stripe-Signature: t=...,v1=...' \
-d '{"id":"evt_test","type":"payment_intent.succeeded","data":{"object":{"id":"pi_123","status":"succeeded"}}}'
curl เพียงครั้งเดียวก็ใช้ได้สำหรับการทดสอบ smoke test แต่มันไม่เพียงพอเมื่อคุณต้องการการทดสอบที่ทำซ้ำได้และได้รับการยืนยันซึ่งทำงานใน CI นั่นคือจุดที่เครื่องมือ API เฉพาะทางเข้ามามีบทบาท
การทดสอบ webhook ด้วย Apidog
Apidog เป็นแพลตฟอร์ม API แบบครบวงจรสำหรับการออกแบบ, ดีบัก, ทดสอบ, mocking และจัดทำเอกสาร API ไม่มี "webhook inbox" โดยเฉพาะ ดังนั้นส่วนนี้จึงจะบอกเล่าอย่างตรงไปตรงมาว่ามันทำอะไรได้ดีจริง ๆ: การสร้าง payloads, การบันทึก, การยืนยัน responses และการทำหน้าที่แทนผู้ให้บริการด้วย mock server
สร้างและบันทึก sample payload เป็น request ที่นำกลับมาใช้ใหม่ได้
นำ payload ที่คุณจับภาพได้จาก webhook.site (หรือคัดลอกมาจากเอกสารของผู้ให้บริการ) และสร้างเป็น Apidog request ตั้งค่าเมธอดเป็น POST วาง JSON body และเพิ่ม headers ที่ผู้ให้บริการส่งมา รวมถึง signature header ที่ handler ของคุณตรวจสอบ
บันทึก request นั้นไว้กับ endpoint ของคุณ ตอนนี้คุณมีวิธีที่ทำซ้ำได้และควบคุมเวอร์ชันได้ในการ POST payload ที่ถูกต้อง (หรือที่สร้างขึ้นโดยเจตนา) ไปยัง handler ของคุณ แทนที่จะต้องพิมพ์คำสั่ง curl ซ้ำทุกครั้ง
ยืนยัน response ด้วยตัวสร้าง visual assertion
การส่ง payload คือครึ่งหนึ่งของการทดสอบ อีกครึ่งหนึ่งคือการตรวจสอบสิ่งที่ handler ของคุณส่งกลับมา ในขั้นตอน request หรือ scenario ให้เปิด Post Processors คลิก "+ เพิ่ม" และเลือก "Assertion" Apidog จะเพิ่มกฎการตรวจสอบที่คุณสามารถกำหนดค่าได้โดยไม่ต้องเขียนโค้ด
ชี้ assertion ไปที่ response body และใช้ $ สำหรับ JSON root ตัวอย่างเช่น กำหนดเป้าหมาย $.data.status ตั้งค่าเงื่อนไขเป็น Equals และเปรียบเทียบกับ succeeded รัน request แล้วผลลัพธ์จะแสดงในแท็บ Assertion การยืนยันด้วยภาพจะเปรียบเทียบค่าเป็นสตริง เมื่อคุณต้องการการตรวจสอบประเภทที่แม่นยำ (ตัวเลขจริง, บูลีน) ให้เปลี่ยนไปใช้สคริปต์ที่กำหนดเองโดยใช้ไวยากรณ์ pm.test ที่เข้ากันได้กับ Postman
สิ่งนี้จะเปลี่ยนจาก "มันส่งคืน 200" เป็น "มันส่งคืน 200, ฟิลด์ status คือ succeeded และ order id ตรงกัน" สร้างการยืนยันหลายรายการใน scenario เดียวเพื่อครอบคลุมเส้นทางที่สำเร็จ กรณีที่ขาดฟิลด์ และการปฏิเสธเนื่องจากลายเซ็นไม่ถูกต้อง
ใช้ mock server เพื่อทำหน้าที่แทนผู้ให้บริการ
บางครั้งคุณอาจต้องการทดสอบในทิศทางตรงกันข้าม: บริการใน stack ของคุณที่เรียกใช้ผู้ให้บริการ ในระหว่างการทดสอบในเครื่อง คุณอาจไม่ต้องการเรียกใช้ผู้ให้บริการจริงเลย Mock server ของ Apidog ช่วยให้คุณทำหน้าที่แทนได้
Apidog มี mock สามประเภท Local Mock ทำงานกับ desktop client และใช้งานได้เฉพาะเมื่อ client เปิดอยู่ Cloud Mock โฮสต์บนเซิร์ฟเวอร์ของ Apidog ทำงานตลอด 24 ชั่วโมงทุกวัน และสามารถเปิดหรือปิดได้ (ปิดอยู่โดยค่าเริ่มต้น) Runner Mock ทำงานบนโครงสร้างพื้นฐาน runner ที่โฮสต์ด้วยตนเองและสามารถใช้ร่วมกันได้ในทีมของคุณ แต่ละ HTTP endpoint มีโมดูล Mock; คัดลอก mock URL จากแท็บ API ในโหมด Design หรือแท็บ Mock ในโหมด Debug เฉพาะ path ที่ขึ้นต้นด้วย / เท่านั้นที่จะถูกส่งไปยัง mock environment ชี้โค้ดของคุณไปยัง mock URL นั้นระหว่างการทดสอบ และการรวมระบบของคุณจะได้รับ provider responses ที่คาดเดาได้ โดยไม่มีการเรียกใช้ API จริงหรือผลข้างเคียง
รันการทดสอบ webhook ใน CI ด้วย Apidog CLI
เมื่อ scenario ของคุณผ่านการทดสอบในเครื่องแล้ว ให้รันมันทุกครั้งที่มีการ push ด้วย Apidog CLI โดยต้องใช้ Node.js v16 หรือใหม่กว่า
npm install -g apidog-cli
node -v && apidog -v && which node && which npm && which apidog # ตรวจสอบการติดตั้ง
รัน scenario ที่บันทึกไว้ทางออนไลน์ โดยส่ง access token และ IDs จากแท็บ "Command line" ของ CI/CD ของ scenario
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 637132 -e 358171 -d 3497013 -r html,cli
ในที่นี้ -t คือ test scenario, -e คือ environment (จำเป็น), -d คือ test data (พาธไฟล์ CSV หรือ JSON, หรือ ID ของชุดข้อมูลที่จัดเก็บไว้), และ -r กำหนด reporters ซึ่งยอมรับ cli, html, json และ junit สำหรับคำแนะนำแบบละเอียดเกี่ยวกับ command-line โปรดดูที่ บทช่วยสอน Apidog CLI
ต้องการสร้างและยืนยันการทดสอบ webhook ของคุณด้วยภาพใช่ไหม? ลองใช้ Apidog ฟรี ไม่ต้องใช้บัตรเครดิต
ขั้นตอนการทำงานสำหรับการทดสอบ webhook แบบทีละขั้นตอน
เมื่อนำเครื่องมือมารวมกัน นี่คือลำดับขั้นตอนที่ทำซ้ำได้
- ตรวจสอบ payload จริง ชี้ผู้ให้บริการไปยัง URL ของ webhook.site และจับภาพเหตุการณ์จริงหนึ่งรายการ สังเกตรูปแบบ body, headers และรูปแบบลายเซ็น
- เข้าถึงโค้ดของคุณ เริ่ม handler ของคุณในเครื่อง, เปิดทันเนลด้วย
ngrok http 3000หรือcloudflaredและใส่ URL สาธารณะลงในการกำหนดค่า webhook ของผู้ให้บริการ - เรียกใช้เหตุการณ์จริง ใช้
stripe trigger, ปุ่ม Redeliver ของ GitHub, หรือ Slack POST เพื่อส่งเหตุการณ์จริงผ่านทันเนล - ตรวจสอบการจัดการลายเซ็น ส่ง payload เดียวกันด้วยลายเซ็นที่ถูกต้อง และอีกครั้งด้วยลายเซ็นที่ถูกแก้ไข handler ของคุณต้องยอมรับอันแรกและปฏิเสธอันที่สอง
- ยืนยัน response และผลข้างเคียง บันทึก payload เป็น Apidog request เพิ่ม assertions บน response body และ status และยืนยันว่า database row หรือการเรียกใช้งาน downstream เกิดขึ้นแล้ว
- ทำให้เป็นอัตโนมัติ ย้าย scenario ไปยัง Apidog CLI เพื่อให้ทำงานใน CI ทุกครั้งที่มีการเปลี่ยนแปลง
หากคุณกำลังออกแบบระบบ webhook ด้วยตนเอง แทนที่จะเป็นเพียงผู้ใช้งาน วิธีการออกแบบ webhook ที่เชื่อถือได้ และ แนวทางปฏิบัติที่ดีที่สุดสำหรับ payment webhook จะครอบคลุมถึงการลองใหม่, idempotency และความปลอดภัย สำหรับภาพรวมที่กว้างขึ้น คู่มือ Webhooks API และ webhooks และ event-driven architecture จะอธิบายว่า webhooks เข้ากับระบบที่ใหญ่ขึ้นได้อย่างไร
คำถามที่พบบ่อย
คุณทดสอบ webhook อย่างไร?
ให้ URL ที่เข้าถึงได้แก่ผู้ให้บริการ เรียกใช้เหตุการณ์จริงหรือเหตุการณ์ทดสอบ จากนั้นยืนยันว่า handler ของคุณได้รับ payload, ตรวจสอบลายเซ็น, ส่งคืน status ที่ถูกต้อง และดำเนินการผลข้างเคียงที่คาดไว้ จับภาพ payload จริงก่อน จากนั้นสร้าง request ที่ทำซ้ำได้พร้อม assertions เพื่อให้การทดสอบทำงานในลักษณะเดียวกันทุกครั้ง
คุณทดสอบ webhook ในเครื่องได้อย่างไร?
รัน handler ของคุณบนพอร์ตในเครื่อง จากนั้นเปิดเผยด้วยทันเนลเพื่อให้ผู้ให้บริการสามารถเข้าถึงเครื่องของคุณได้ ใช้ ngrok http 3000 หรือ cloudflared tunnel --url http://localhost:3000, วาง URL สาธารณะแบบ HTTPS ลงในการตั้งค่า webhook ของผู้ให้บริการ และเรียกใช้เหตุการณ์ request ที่เข้ามาจะมาถึงเซิร์ฟเวอร์ในเครื่องของคุณ ซึ่งคุณสามารถตั้งค่า breakpoints และตรวจสอบได้แบบสด
คุณทดสอบ webhook ด้วย Postman อย่างไร?
Postman สามารถ POST payload ที่สร้างขึ้นไปยัง endpoint ของคุณและยืนยัน response ได้ แต่ไม่สามารถรับ inbound webhook จริงได้ด้วยตัวเอง เช่นเดียวกับ Apidog: คุณสร้าง request ด้วย payload และ headers ของผู้ให้บริการ เพิ่ม assertions บน response body และ status และบันทึกเป็น test ที่นำกลับมาใช้ใหม่ได้ หากต้องการจับภาพเหตุการณ์ inbound ที่แท้จริง ให้ใช้เครื่องมือร่วมกับบริการจับภาพหรือทันเนล
คุณทดสอบ Stripe webhooks อย่างไร?
ใช้ Stripe CLI รัน stripe listen --forward-to localhost:3000/webhooks เพื่อส่งต่อเหตุการณ์ sandbox ไปยัง handler ของคุณและรับ signing secret จากนั้นรัน stripe trigger payment_intent.succeeded (หรือเหตุการณ์ใดก็ได้จาก stripe trigger --help) เพื่อเรียกใช้เหตุการณ์ทดสอบจริง การเรียกใช้จะสร้าง API objects ที่มีข้อมูลรองรับและสามารถเกิดเหตุการณ์ต่อเนื่องได้ ดังนั้น payment_intent.succeeded จึงปล่อย payment_intent.created ออกมาด้วย
คุณทดสอบ Slack webhook อย่างไร?
POST JSON ไปยัง URL ของ incoming webhook payload ที่ถูกต้องขั้นต่ำคือ {"text":"Hello, world."} ซึ่งส่งพร้อมกับ header Content-type: application/json การทดสอบที่สำเร็จจะโพสต์ข้อความไปยังช่องที่กำหนดค่าไว้ เก็บ URL ไว้เป็นความลับ เนื่องจาก Slack จะเพิกถอน URL ของ webhook ที่รั่วไหล
คุณทดสอบ URL ของ webhook อย่างไร?
ส่ง sample POST ไปยัง URL และยืนยันว่ามันส่งคืน success status และทำงานได้อย่างถูกต้อง การตรวจสอบที่เร็วที่สุดคือคำสั่ง curl เพียงครั้งเดียวพร้อม body ที่เป็นตัวแทน สำหรับการทดสอบจริง ให้จับภาพ payload จริงก่อน ส่งด้วยลายเซ็นที่ถูกต้องและไม่ถูกต้อง และยืนยัน response และผลข้างเคียง แทนที่จะเพียงแค่ตรวจสอบ 200