Skip to main content

GitHub Repository

الدليل الكامل للشفرة المصدرية وإعدادها
اطّلع على Dodo Payments Supabase Subscription Starter — وهو قالب جاهز متكامل لـ Next.js وSupabase وDodo Payments، يتضمن المصادقة والمدفوعات وwebhooks.

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

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

ستحتاج إلى:
  • حساب Supabase مع إنشاء مشروع
  • مفتاح API لـ Dodo Payments من Developer → API Keys في لوحة التحكم

2. المصادقة والربط

ابحث عن مرجع مشروعك ضمن Project Settings في لوحة تحكم Supabase.

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

  1. انتقل إلى لوحة تحكم Supabase.
  2. افتح SQL Editor.
  3. انسخ المحتوى الكامل لـ schema.sql وشغّله.

4. تعيين الأسرار الأولية

يوفّر Supabase تلقائيًا كلًا من SUPABASE_URL وSUPABASE_SERVICE_ROLE_KEY أثناء التشغيل.
ستعيّن DODO_PAYMENTS_WEBHOOK_KEY بعد النشر، بمجرد حصولك على عنوان URL الخاص بـ webhook.

5. النشر

تم إعداد الدالة مسبقًا في functions/webhook/index.ts.

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

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

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

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

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

ما الذي يفعله

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

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

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

ملفات الإعداد

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

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

كود التنفيذ

آلية العمل

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

الاختبار

التطوير المحلي:
مطلوب استخدام العلامة --no-verify-jwt لأن webhooks لا تتضمن رموز JWT. ويوفّر التحقق من توقيع webhook الحماية اللازمة.
عرض السجلات:
أو في لوحة تحكم Supabase ضمن Edge Functions → webhook → Logs. الإعداد في لوحة تحكم Dodo Payments:
  1. انتقل إلى Developer → Webhooks.
  2. أضف endpoint باستخدام عنوان URL الخاص بـ Supabase.
  3. حدّد subscription.active وsubscription.cancelled وsubscription.renewed.

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

الموارد

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