دليل عملي · إجابة موثَّقة المصادر

كيف تعمل webhooks في Resend؟

تعمل webhooks في Resend بإرسال طلب HTTPS POST يحمل حمولة حدث بصيغة JSON إلى نقطة النهاية المسجَّلة لديك عند وقوع حدث يخص رسالة أو جهة اتصال أو نطاقًا أو قائمة منع. ينبغي أن تتحقق نقطة النهاية من التوقيع مقابل نص الطلب الخام، وتعالج الحدث معالجة غير مكرّرة، وتعيد استجابة ناجحة بسرعة.

سير عمل webhook في Resend

يبدأ سير العمل عندما تنشئ نقطة نهاية HTTPS عامة وتسجّلها في Resend مع أنواع الأحداث التي يحتاجها تطبيقك. وعند وقوع حدث مطابق، يرسل Resend طلب POST يتضمن حمولة JSON. تشمل الحمولة نوعًا (type) مثل email.sent أو email.delivered أو email.bounced أو email.complained، ووقت الإنشاء، وبيانات خاصة بالحدث. وجّه المعالجة بحسب الحقل type ولا تفترض أن لكل الحمولات البنية نفسها.

تحقق من الطلب قبل معالجته

اقرأ الطلب كنص خام وتحقق منه باستخدام سر توقيع webhook مع الترويسات svix-id وsvix-timestamp وsvix-signature. افعل ذلك قبل تحليل الحمولة أو التصرف بناءً عليها. فتحليل JSON ثم إعادة تسلسله قد يغيّر البايتات ويجعل توقيعًا صحيحًا يفشل. ارفض الطلبات التي لا تجتاز التحقق، واحتفظ بسر التوقيع في مدير أسرار أو متغير بيئة محمي بدلًا من الشيفرة المصدرية.

اجعل معالجة الأحداث غير مكرّرة

يوثّق Resend أن التسليم يتم مرة واحدة على الأقل (at-least-once)، لذا قد يصل الحدث نفسه إلى نقطة النهاية أكثر من مرة. خزّن svix-id مع قيد تفرّد (uniqueness constraint) وتخطَّ منطق العمل إذا سبقت معالجة هذا المعرّف. ولا تعتمد كذلك على ترتيب الوصول، لأن إعادة المحاولة وتأخر الشبكة قد يعيدان ترتيب الأحداث. استخدم قيمة created_at للحدث عندما يكون التسلسل مهمًا، وصمّم تغييرات الحالة بحيث لا يستطيع حدث أقدم أن يستبدل حالة أحدث عن غير قصد.

أقرّ بالاستلام بسرعة وعالج بأمان

أعد HTTP 200 بعد التحقق من الحدث وتسجيله بشكل دائم، ثم نفّذ الأعمال الأبطأ عبر طابور أو عامل في الخلفية. فانتهاء المهلة أو الاستجابة غير الناجحة يسبب محاولة تسليم أخرى، ولذلك تتسبب المعالجات المتزامنة الطويلة في تكرارات يمكن تجنبها. افصل الاستقبال عن الآثار الجانبية مثل تحديث سجل المنع أو إشعار الدعم أو تسجيل ارتداد. ويجب أن يكون كل أثر جانبي آمنًا عند تكراره أو محميًا بمعرّف الحدث المخزَّن.

اختبر إعادة المحاولة وإعادة التشغيل والتعافي من الأعطال

اختبر نقطة النهاية بأنواع أحداث تمثيلية قبل بيئة الإنتاج، بما في ذلك التوقيعات غير الصالحة والمعرّفات المكررة والطوابع الزمنية غير المرتبة وأعطال قاعدة البيانات المؤقتة. يعيد Resend محاولة التسليمات الفاشلة وفق جدول تراجع (backoff)، ويتيح لك إعادة تشغيل رسائل webhook الفاشلة والناجحة على حد سواء. استخدم إعادة التشغيل للتعافي بعد انقطاع أو للتحقق من شيفرة معالج محدّثة، لكن أبقِ إزالة التكرار مفعّلة حتى لا يكرر التعافي آثارًا جانبية ظاهرة للعملاء.

أسئلة تطرحها الفرق

ما الاستجابة التي ينبغي أن تعيدها نقطة نهاية webhook في Resend؟

أعد HTTP 200 بعد التحقق من الطلب وقبول الحدث بشكل دائم. ينبغي أن يستمر العمل البطيء بشكل غير متزامن حتى لا يعيد المزوّد المحاولة بسبب انتهاء المهلة.

لماذا يجب الحفاظ على نص الطلب الخام؟

يغطي التوقيع بايتات الطلب الأصلية. وقد يغيّر تحليل JSON وإعادة تسلسله تلك البايتات، فيفشل التحقق حتى لو كان الطلب صحيحًا.

هل يمكن تسليم حدث webhook في Resend أكثر من مرة؟

نعم. يوثّق Resend أن التسليم يتم مرة واحدة على الأقل، لذا يجب أن تزيل المعالجات تكرار الأحداث، عادةً بتخزين svix-id الفريد قبل تطبيق أي آثار جانبية.

هل تُسلَّم أحداث webhook في Resend بالترتيب؟

لا. فقد يغيّر تأخر الشبكة وإعادة المحاولة ترتيب الوصول. استخدم الطوابع الزمنية للأحداث وقواعد انتقال الحالة عندما يحتاج تطبيقك إلى إعادة بناء تسلسل موثوق.

كيف ينبغي التعافي من تسليمات webhook الفاشلة في Resend؟

يعيد Resend محاولة التسليمات الفاشلة تلقائيًا ويدعم أيضًا إعادة التشغيل يدويًا. أصلح نقطة النهاية أولًا، ثم أعد تشغيل الأحداث اللازمة مع إبقاء فحوصات عدم التكرار مفعّلة.