Skip to main content

GitHub Repository

رمز المصدر الكامل ودليل الإعداد

الإعداد السريع

1. المتطلبات الأساسية

تحتاج إلى:

2. تثبيت Dependencies

3. إعداد قاعدة البيانات

  1. سجّل في Neon وأنشئ مشروعًا.
  2. افتح SQL Editor.
  3. انسخ المحتوى الكامل لـ schema.sql وشغّله.
  4. انسخ connection string من Connection Details.

4. تعيين Environment Variables الأولية

ستعيّن DODO_PAYMENTS_WEBHOOK_KEY بعد النشر، بعد حصولك على webhook URL.

5. النشر

6. احصل على عنوان URL الخاص بـ Webhook

عنوان URL الخاص بـ webhook هو:

7. تسجيل Webhook في لوحة تحكم DodoPayments

  1. انتقل إلى Developer → Webhooks في لوحة تحكم Dodo Payments.
  2. انقر على Add endpoint.
  3. أدخل webhook URL الخاص بك.
  4. حدّد هذه الأحداث: subscription.active، subscription.cancelled، subscription.renewed.
  5. انقر على Create endpoint وانسخ signing secret.

8. تعيين مفتاح Webhook وإعادة النشر

ماذا يفعل

يعالج webhook handler أحداث الاشتراكات ويخزّنها في PostgreSQL:
  • subscription.active — ينشئ سجلات العملاء والاشتراكات أو يحدّثها
  • subscription.cancelled — يحدّد الاشتراك على أنه ملغى
  • subscription.renewed — يحدّث تاريخ الفوترة التالي

الميزات الرئيسية

  • التحقق من التوقيع — يستخدم Dodo Payments SDK للتحقق من صحة webhook
  • Idempotency — يستخدم webhook-id header لمنع المعالجة المكررة
  • تسجيل الأحداث — يخزّن جميع الأحداث في جدول webhook_events لأغراض التدقيق
  • معالجة الأخطاء — يسجّل حالات الفشل ويضع علامة على الأحداث لإعادة المحاولة
يتعامل هذا المثال مع ثلاثة أحداث أساسية للاشتراكات باستخدام الحد الأدنى من الحقول. يمكنك توسيعه لدعم أنواع وحقول أحداث إضافية وفقًا لاحتياجاتك.

ملفات التكوين

مخطط قاعدة البيانات

الجداول التي تم إنشاؤها:
  • customers — البريد الإلكتروني والاسم ومعرّف عميل Dodo Payments
  • subscriptions — الحالة والمبلغ وتاريخ الفوترة التالي، مرتبط بالعملاء
  • webhook_events — سجل الأحداث مع webhook ID لضمان Idempotency

كود التنفيذ

كيف يعمل

يقوم webhook handler بما يلي:
  1. يعطّل تحليل body — للوصول إلى body الخام للتحقق من التوقيع
  2. يتحقق من التوقيع — يستخدم Dodo Payments SDK للتحقق من الطلب باستخدام HMAC-SHA256
  3. يتحقق من التكرار — يستخدم webhook-id header لمنع معالجة الحدث نفسه مرتين
  4. يسجّل الحدث — يخزّن webhook الخام في جدول webhook_events لأغراض التدقيق
  5. يعالج الحدث — ينشئ العملاء والاشتراكات أو يحدّثها في Neon
  6. يعالج الأخطاء — يسجّل حالات الفشل ويضع علامة على الأحداث التي لم تتم معالجتها لإعادة المحاولة

الاختبار

التطوير المحلي:
عرض السجلات في لوحة تحكم Vercel:
  1. حدّد مشروعك.
  2. انتقل إلى Deployments → أحدث عملية نشر.
  3. انقر على Functions → Logs.
الإعداد في لوحة تحكم Dodo Payments:
  1. انتقل إلى Developer → Webhooks.
  2. أضف نقطة نهاية باستخدام Vercel Functions URL الخاص بك.
  3. حدّد subscription.active وsubscription.cancelled وsubscription.renewed.

المشكلات الشائعة

الموارد

آخر تعديل في ٢٦ سبتمبر ٢٠٢٦