วิธีทำ · คำตอบพร้อมแหล่งอ้างอิง

Webhook ของ Resend ทำงานอย่างไร

Webhook ของ Resend ทำงานโดยส่ง HTTPS POST พร้อม payload อีเวนต์แบบ JSON ไปยัง endpoint ที่คุณลงทะเบียนไว้ เมื่อเกิดอีเวนต์เกี่ยวกับอีเมล รายชื่อผู้ติดต่อ โดเมน หรือการระงับการส่ง endpoint ของคุณควรตรวจสอบลายเซ็นกับเนื้อหาคำขอแบบดิบ ประมวลผลอีเวนต์แบบ idempotent และส่งการตอบกลับที่สำเร็จโดยเร็ว

ขั้นตอนการทำงานของ webhook ใน Resend

ขั้นตอนเริ่มจากการสร้าง endpoint HTTPS สาธารณะและลงทะเบียนใน Resend พร้อมประเภทอีเวนต์ที่แอปพลิเคชันของคุณต้องการ เมื่อเกิดอีเวนต์ที่ตรงกัน Resend จะส่งคำขอ POST ที่มี payload แบบ JSON payload ประกอบด้วย type เช่น email.sent, email.delivered, email.bounced หรือ email.complained เวลาที่สร้าง และข้อมูลเฉพาะของอีเวนต์ ให้กำหนดเส้นทางการประมวลผลตามฟิลด์ type แทนที่จะสมมติว่าทุก payload มีรูปแบบเดียวกัน

ตรวจสอบคำขอก่อนประมวลผล

อ่านคำขอเป็นข้อความดิบ และตรวจสอบด้วย webhook signing secret ร่วมกับเฮดเดอร์ svix-id, svix-timestamp และ svix-signature ทำขั้นตอนนี้ก่อนแยกวิเคราะห์หรือดำเนินการกับ payload การแยกวิเคราะห์ JSON แล้วแปลงกลับเป็นสตริงอีกครั้งอาจเปลี่ยนไบต์และทำให้ลายเซ็นที่ถูกต้องล้มเหลว ให้ปฏิเสธคำขอที่ไม่ผ่านการตรวจสอบ และเก็บ signing secret ไว้ใน secret manager หรือตัวแปรสภาพแวดล้อมที่ได้รับการป้องกัน ไม่ใช่ในซอร์สโค้ด

ทำให้การจัดการอีเวนต์เป็น idempotent

Resend ระบุว่าส่งแบบ at-least-once ดังนั้นอีเวนต์เดียวกันอาจมาถึง endpoint ของคุณมากกว่าหนึ่งครั้ง ให้เก็บ svix-id ด้วย uniqueness constraint และข้ามตรรกะทางธุรกิจเมื่อตัวระบุนั้นถูกประมวลผลแล้ว อย่าพึ่งลำดับการมาถึงด้วย เพราะการลองใหม่และความล่าช้าของเครือข่ายอาจทำให้ลำดับอีเวนต์สลับกัน ใช้ค่า created_at ของอีเวนต์เมื่อลำดับมีความสำคัญ และออกแบบการเปลี่ยนสถานะเพื่อไม่ให้อีเวนต์เก่าเขียนทับสถานะใหม่โดยไม่ตั้งใจ

ตอบรับอย่างรวดเร็วและประมวลผลอย่างปลอดภัย

ส่ง HTTP 200 กลับหลังจากตรวจสอบอีเวนต์และบันทึกอย่างคงทนแล้ว จากนั้นทำงานที่ช้ากว่าผ่านคิวหรือ background worker การ timeout หรือการตอบกลับที่ไม่สำเร็จทำให้เกิดความพยายามส่งอีกครั้ง ดังนั้น handler แบบซิงโครนัสที่ทำงานนานจึงสร้างรายการซ้ำที่หลีกเลี่ยงได้ แยกการรับเข้าออกจากผลข้างเคียง เช่น การอัปเดตระเบียนการระงับการส่ง การแจ้งซัพพอร์ต หรือการบันทึกอีเมลตีกลับ ผลข้างเคียงแต่ละอย่างควรทำซ้ำได้อย่างปลอดภัยหรือมีตัวระบุอีเวนต์ที่จัดเก็บไว้ป้องกัน

ทดสอบการลองใหม่ การเล่นซ้ำ และการกู้คืนจากความล้มเหลว

ทดสอบ endpoint ด้วยอีเวนต์ประเภทตัวแทนก่อนใช้งานจริง รวมถึงลายเซ็นไม่ถูกต้อง ตัวระบุซ้ำ ไทม์สแตมป์ที่ไม่เรียงลำดับ และความล้มเหลวชั่วคราวของฐานข้อมูล Resend ลองส่งซ้ำการส่งที่ล้มเหลวตามตาราง backoff และให้คุณเล่นซ้ำ (replay) ข้อความ webhook ได้ทั้งที่ล้มเหลวและสำเร็จ ใช้ replay เพื่อกู้คืนหลังระบบล่มหรือตรวจสอบโค้ด handler ที่อัปเดต แต่ต้องเปิดการตัดรายการซ้ำไว้ เพื่อไม่ให้การกู้คืนทำซ้ำผลข้างเคียงที่ลูกค้าเห็น

คำถามที่ทีมมักถาม

endpoint ของ webhook ใน Resend ควรตอบกลับด้วยอะไร

ส่ง HTTP 200 หลังจากคำขอได้รับการตรวจสอบและยอมรับอีเวนต์อย่างคงทนแล้ว งานที่ช้าควรทำต่อแบบอะซิงโครนัส เพื่อไม่ให้ผู้ให้บริการลองใหม่เพราะ timeout

ทำไมต้องเก็บเนื้อหาคำขอแบบดิบไว้

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

อีเวนต์ webhook ของ Resend อาจถูกส่งมากกว่าหนึ่งครั้งได้หรือไม่

ได้ Resend ระบุว่าส่งแบบ at-least-once ดังนั้น handler ต้องตัดอีเวนต์ซ้ำ โดยทั่วไปด้วยการจัดเก็บ svix-id ที่ไม่ซ้ำก่อนดำเนินการผลข้างเคียงทางธุรกิจ

อีเวนต์ webhook ของ Resend ถูกส่งตามลำดับหรือไม่

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

ควรกู้คืนการส่ง webhook ของ Resend ที่ล้มเหลวอย่างไร

Resend ลองส่งซ้ำการส่งที่ล้มเหลวโดยอัตโนมัติ และรองรับการเล่นซ้ำด้วยตนเอง ให้แก้ไข endpoint ก่อน แล้วจึงเล่นซ้ำอีเวนต์ที่ต้องการ โดยเปิดการตรวจสอบ idempotency ไว้