الويب هوك: استقبال أحداث الدفع في نظامك

يتيح لك الويب هوك أن يُشعر ستريم خادمك فور حدوث أي شيء: نجاح دفعة، اكتمال فاتورة، تجديد اشتراك. وهو الطريقة الموثوقة لتأكيد حركة الأموال، أما معاملات إعادة التوجيه فلا يُعتمد عليها.

والسلوك متطابق في البيئة التجريبية والإنتاج.

كيف تضيف واحدًا

من لوحة التحكم اذهب إلى الإعدادات ← الويب هوك، ثم اختر إنشاء ويب هوك. أدخل اسمًا للويب هوك، ورابط الاستقبال على خادمك، والمفتاح السري، ثم اختر الأحداث التي تريد إشعارك بها. تعامل مع هذا المفتاح كما تتعامل مع كلمة المرور، ولا تضعه أبدًا في كود المتصفح أو التطبيق.

ما الذي يرسله ستريم

{
  "webhook_delivery_id": "uuid",
  "event_type": "PAYMENT_SUCCEEDED",
  "entity_type": "PAYMENT",
  "entity_id": "uuid",
  "entity_url": "https://stream-app-service.streampay.sa/api/v2/payments/{id}",
  "status": "SUCCEEDED",
  "data": { ... },
  "timestamp": "2025-07-15T14:41:21.705Z"
}

يحمل data بيانات الدفعة والفاتورة ومعرّف العميل والبيانات الوصفية ورابط الدفع والاشتراك، وتكون فارغة حين لا تنطبق. وtimestamp هو وقت الحدث بتوقيت UTC دون إزاحة.

ربط الأحداث بسجلاتك

الحقل data.metadata هو custom_metadata الذي ضبطته عند إنشاء رابط الدفع، أو {}. ويُضبط مرة واحدة عند الإنشاء ولا يمكن تعديله بعدها، فكل ويب هوك لذلك الرابط، بما فيها تجديدات الاشتراك، يحمل القيمة نفسها. استخدم data.invoice.id أو data.payment.id للتفريق بين دورات التجديد.

أما الاشتراكات المنشأة عبر الواجهة البرمجية مباشرة لا عبر رابط دفع فلا تحمل بيانات وصفية: تصل ويب هوكاتها بـmetadata: {} وpayment_link: null، لكنها تحمل customer_id، فاستدعِ GET /api/v2/consumers/{id} إن احتجت مرجعك الخاص.

الترويسات

  • X-Webhook-Event وX-Webhook-Entity-Type وX-Webhook-Entity-ID
  • X-Webhook-Timestamp
  • X-Webhook-Signature — بصيغة t=<unix seconds>,v1=<hex signature>
  • User-Agent: StreamApp-Webhook/1.0

تحقق من التوقيع

كوّن النص "{t}.{raw_request_body}" من البايتات الخام لجسم الطلب كما وصلت تمامًا، واحسب HMAC-SHA256 بالمفتاح السري للويب هوك، وحوّله إلى hex، وقارنه بـv1 بمقارنة ثابتة الزمن. وإذا حللت الـ JSON ثم أعدت تحويله قبل التشفير فلن يتطابق التوقيع.

واستخدم تسامحًا زمنيًا قدره ±٥ دقائق مقابل ساعة خادمك بتوقيت UTC. وكل محاولة تُوقَّع من جديد بطابع زمني جديد، سواء كانت إعادة محاولة تلقائية أو إعادة إرسال يدوية، فتجتاز المحاولة المتأخرة بساعات هذا الفحص. أما الجسم نفسه فلا يتغير بين المحاولات.

import hmac, hashlib

def verify(secret, raw_body, header):
    parts = dict(p.split("=", 1) for p in header.split(","))
    msg = f"{parts['t']}.{raw_body.decode()}"
    expected = hmac.new(secret.encode(), msg.encode(), hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts["v1"])

ما الذي يُعد تسليمًا ناجحًا وما الذي يُعاد

  • النجاح: أي استجابة 2xx خلال ١٥ ثانية. أرجع 2xx فور التحقق من التوقيع، ثم نفّذ المعالجة الثقيلة بعد ذلك.
  • يُعاد إرسالها: أخطاء 5xx، والمهلة المنتهية، وأخطاء الاتصال، و408 و429.
  • لا يُعاد إرسالها: بقية أخطاء 4xx بما فيها 409 و422، وكذلك تحويلات 3xx. فيجب أن يكون رابط الويب هوك الوجهة النهائية لا تحويلًا.

والجدول هو عدة محاولات سريعة، ثم نحو ٥ دقائق و٣٠ دقيقة وساعتين و٦ ساعات. وإذا لم ينجح التسليم خلال ٨٫٥ ساعة تقريبًا تُعلَّم الإرسالية FAILED، ويبقى بالإمكان إعادة إرسالها يدويًا بعد ذلك.

إذا استمر إخفاق نقطتك، يُعطَّل الويب هوك

بعد عدة إخفاقات متتالية في التسليم، يعطّل ستريم الويب هوك تلقائيًا ويرسل لك إشعارًا بذلك. وهذا سلوك وقائي لا خلل.

وللمعالجة: تأكد أن نقطتك قابلة للوصول وتستجيب بشكل صحيح، ثم أعد إرسال إرسالية. ويعود الويب هوك للعمل بمجرد نجاح تسليم واحد.

إعادة الإرسال ومراجعة السجلات

يمكنك إعادة إرسال أي إرسالية من صفحة إدارة الويب هوك في اللوحة، أو عبر الواجهة البرمجية بـPOST /api/v2/webhook-deliveries/{webhook_delivery_id}. وإعادة الإرسال ترسل الحمولة المخزنة الأصلية دون تغيير، بما فيها بياناتها الوصفية وطابعها الزمني، ولا يتغير سوى ترويستي التوقيع والطابع الزمني.

ويُرجع GET /api/v2/webhook-deliveries/{id} السجل الكامل: الحمولة المرسلة بالضبط، وstatus (PENDING وDELIVERED وRETRYING وMANUAL_RETRYING وFAILED وCANCELLED)، وretry_count وattempt_count وnext_retry_at وdelivered_at، ورمز استجابة آخر محاولة وجسمها وترويساتها وخطأها.

ولا يوجد زر «إرسال ويب هوك تجريبي». وللاختبار، أطلق حدثًا حقيقيًا في البيئة التجريبية، كدفعة فاشلة ببطاقة اختبار مرفوضة.

امنع التكرار عبر webhook_delivery_id

الترتيب غير مضمون والتكرار يحدث فعلًا، فيجب أن يكون معالجك آمنًا عند التنفيذ مرتين. تحقق من الحالة الراهنة قبل أن تتصرف.

وامنع التكرار عبر webhook_delivery_id، وهو حقل رئيسي في الجسم. يبقى ثابتًا عبر إعادات المحاولة وإعادات الإرسال للإرسالية نفسها، بينما يأخذ الحدث الجديد فعلًا معرّفًا جديدًا.

ولا تمنع التكرار عبر entity_id مع event_type، فبعض الأحداث تتكرر بحق للكيان نفسه: PAYMENT_PARTIALLY_REFUNDED مع كل استرجاع جزئي، وINVOICE_UPDATED مع كل تعديل، وأحداث التجديد كل دورة، وبذلك ستُسقط أحداثًا حقيقية بصمت.

الأحداث المتاحة

المدفوعات

PAYMENT_SUCCEEDED، PAYMENT_FAILED، PAYMENT_CANCELED، PAYMENT_PARTIALLY_REFUNDED، PAYMENT_REFUNDED، PAYMENT_MARKED_AS_PAID

الفواتير

INVOICE_CREATED، INVOICE_SENT، INVOICE_ACCEPTED، INVOICE_REJECTED، INVOICE_COMPLETED، INVOICE_CANCELED، INVOICE_UPDATED

الاشتراكات

SUBSCRIPTION_CREATED، SUBSCRIPTION_ACTIVATED، SUBSCRIPTION_INACTIVATED، SUBSCRIPTION_CANCELED، SUBSCRIPTION_FROZEN، SUBSCRIPTION_CYCLE_RENEWED_SUCCESSFULLY، SUBSCRIPTION_CYCLE_RENEWAL_FAILED، ومجموعة تغيير الباقة.

روابط الدفع

PAYMENT_LINK_PAY_ATTEMPT_FAILED هو الحدث الوحيد لروابط الدفع. ولا يوجد حدث عند تعطيل الرابط أو انتهائه أو اكتماله.

أي حدث يُطلق عند الإخفاق

  • محاولة دفع فاشلة على رابط ترسل PAYMENT_LINK_PAY_ATTEMPT_FAILED فقط. فالرابط لا ينشئ الفاتورة والدفعة إلا بعد النجاح، فلا يوجد سجل دفعة ليفشل ولا يُرسل PAYMENT_FAILED.
  • تجديد اشتراك فاشل يرسل كلا الحدثين PAYMENT_FAILED وSUBSCRIPTION_CYCLE_RENEWAL_FAILED. اعتمد على PAYMENT_FAILED لأنه يحمل بيانات الربط الكاملة، بينما لا يحمل حدث التجديد سوى {"payment_id": ...}.

الأقساط والتجديد

  • كل قسط مدفوع يرسل PAYMENT_SUCCEEDED مستقلًا، ولا يُرسل INVOICE_COMPLETED إلا بعد سداد جميع الأقساط.
  • والتجديد الناجح ينتج INVOICE_CREATED ثم PAYMENT_SUCCEEDED ثم INVOICE_COMPLETED، مع SUBSCRIPTION_CYCLE_RENEWED_SUCCESSFULLY.

حالة تكرار واحدة ينبغي معالجتها

يُفحص max_number_of_payments: 1 عند فتح صفحة الدفع لا عند اكتمال الدفعة. فإذا فُتحت صفحتا دفع قبل اكتمال الأولى، سواء من عميلين أو من عميل واحد في نافذتين، فقد تُدفعان معًا. وهذا نادر لكنه يستحق المعالجة.

واكتشفه بوصول PAYMENT_SUCCEEDED ثانٍ بنفس data.payment_link.id وباختلاف data.invoice.id، ثم استرجع الدفعة الزائدة عبر POST /api/v2/payments/{id}/refund.

هل ما زلت تحتاج إلى مساعدة؟

لا تتردد في التواصل مع فريق الدعم. ارسل لنا بريدًا إلكترونيًا أو اتصل بنا وسنرد عليك في أسرع وقت ممكن

جميع الحقوق محفوظة © 2026