تلقي Webhooks

للمعالجة الناجحة لـ webhooks، يجب عليك دائمًا إرجاع الاستجابة التالية؛ وإلا فسيستمر النظام في إعادة المحاولة (حتى 30 مرة):

{
  "success": true
}

1. Webhook: تم استلام الدفعة

يمكنك تكوين عناوين URL لتلقي إشعارات الدفع في صفحة إعدادات المشروع.
يتم إرسال هذا الـ webhook عند تأكيد الدفعة على سلسلة الكتل واعتمادها.

مثال: Webhook استلام الدفعة

{
  "amount": "2.395", - مبلغ الدفعة بالدولار الأمريكي
  "created_at": "2025-03-17T12:57:52.449795Z", - وقت إنشاء الدفعة
  "paid_at": "2025-03-17T12:57:19Z", - وقت تأكيد الدفعة
  "status": "completed", - حالة الدفعة
  "transactions": {
    "amount": "0.02552778", - مبلغ الدفعة بالعملة الرقمية
    "amount_usd": "2.395", - مبلغ الدفعة بالدولار الأمريكي
    "bc_uniq_key": "0", - الرقم التسلسلي داخل المعاملة (مهم للشبكات المشابهة لـ BTC؛ يضمن bc_uniq_key + tx_hash التفرد)
    "blockchain": "litecoin", - اسم سلسلة الكتل
    "created_at": "2025-03-17T12:57:52.449795Z", - وقت إنشاء الدفعة
    "currency": "LTC", - رمز العملة الرقمية
    "currency_id": "LTC.Litecoin", - معرّف العملة الرقمية
    "tx_hash": "2be41b0cad76bc5699c3da5d5a1d390f9fb4038e5bfe49aec3b675f9dd4515fd", - تجزئة المعاملة
    "tx_id": "4bbc91fd-a950-4fd0-83f3-9f1c09a6b54f" - معرّف المعاملة في نظام التاجر
  },
  "type": "PaymentReceived", - نوع الـ webhook
  "wallet": {
    "id": "9a07b545-f99e-4f51-bf37-a84fcbe4df4d", - المعرّف الداخلي للمستخدم
    "store_external_id": "1" - المعرّف الخارجي للمستخدم
  }
}

2. Webhook: دفعة في الـ Mempool (بانتظار التأكيد)

يتم إرسال هذا الـ webhook عندما تدخل الدفعة إلى الـ mempool لكنها لم تحصل بعد على عدد التأكيدات المطلوب.
سيتم اعتماد الأموال فقط بعد التأكيد (بعد استلام الـ PaymentReceived webhook).

ملاحظة: جميع الحقول في هذا النوع من webhooks تحمل البادئة unconfirmed_.

مثال: Webhook الدفعة في الـ Mempool

{
  "unconfirmed_amount":"1000000000000", - مبلغ الدفعة بالدولار الأمريكي (غير مؤكد)
  "unconfirmed_created_at":"2025-10-06T12:39:39.457399475", - وقت إنشاء الدفعة (غير مؤكد)
  "unconfirmed_paid_at":"2025-10-06T12:39:39.457399475", - وقت الدفع (غير مؤكد)
  "unconfirmed_status":"completed", - حالة الدفعة (غير مؤكدة)
  "unconfirmed_transactions":{
    "unconfirmed_amount":"1000000000000", - مبلغ الدفعة بالعملة الرقمية (غير مؤكد)
    "unconfirmed_amount_usd":"1000000000000", - مبلغ الدفعة بالدولار الأمريكي (غير مؤكد)
    "unconfirmed_bc_uniq_key":"bc_uniq_key_example", - الرقم التسلسلي للمعاملة (لأغراض عدم التكرار)
    "unconfirmed_blockchain":"bitcoin", - اسم سلسلة الكتل
    "unconfirmed_created_at":"2025-10-06T12:39:39.457399475", - وقت إنشاء الدفعة (غير مؤكد)
    "unconfirmed_currency":"BTC", - رمز العملة الرقمية
    "unconfirmed_currency_id":"BTC.Bitcoin", - معرّف العملة الرقمية
    "unconfirmed_tx_hash":"tx_hash_example", - تجزئة المعاملة (لأغراض عدم التكرار)
    "unconfirmed_tx_id":"165d8dd3-0d9b-4144-979e-23f593f48cdf" - معرّف المعاملة في نظام التاجر
  },
  "unconfirmed_type":"PaymentNotConfirmed", - نوع الـ webhook: دفعة بانتظار التأكيد
  "unconfirmed_wallet":{
    "unconfirmed_id":"5f185a18-a8d5-469d-a853-7fbcb048635b", - المعرّف الداخلي للمستخدم
    "unconfirmed_store_external_id":"store_external_example" - المعرّف الخارجي للمستخدم
  }
}

3. Webhook: سحب من محفظة المعالجة

يُخطرك هذا الـ webhook بأن الأموال التي أرسلتها لمستخدميك عبر الخدمة قد تم اعتمادها بنجاح في محفظة المستلم.

مثال: Webhook السحب من محفظة المعالجة

{
  "amount": "100", - مبلغ السحب بالدولار الأمريكي
  "created_at": "2025-09-23T12:27:08.166963191", - وقت إنشاء السحب
  "paid_at": "2025-09-23T12:27:08.166963191", - وقت تنفيذ السحب فعليًا
  "status": "completed", - حالة السحب
  "transactions": {
    "amount": "100", - مبلغ السحب بالعملة الرقمية
    "amount_usd": "100", - مبلغ السحب بالدولار الأمريكي
    "bc_uniq_key": "bc_uniq_key_example", - معرّف فريد للحدث (لأغراض عدم التكرار)
    "blockchain": "bitcoin", - اسم سلسلة الكتل
    "created_at": "2025-09-23T12:27:08.166963191", - وقت إنشاء المعاملة
    "currency": "BTC", - رمز العملة الرقمية
    "currency_id": "BTC.Bitcoin", - معرّف العملة الرقمية
    "tx_hash": "tx_hash_example", - تجزئة معاملة سلسلة الكتل (لأغراض عدم التكرار)
    "tx_id": "408a97b1-d1e3-423e-9c8b-5ae4cd902f7f" - معرّف المعاملة في نظام التاجر
  },
  "type": "WithdrawalFromProcessingReceived", - نوع الـ webhook: إشعار بإتمام السحب
  "wallet": {
    "id": "8a279ec7-31fb-41f2-a2a5-3d066b77bd8a", - المعرّف الداخلي لمحفظة المرسل (المعالجة)
    "store_external_id": "store_external_example" - معرّف المستخدم/المتجر الخارجي
  }
}

التحقق من عدم التكرار عند استلام Webhooks

عند معالجة webhooks الواردة، من الضروري ضمان خاصية عدم التكرار لتجنّب معالجة الحدث مرتين (مثل الاعتماد المزدوج).
لتحقيق ذلك، استخدم الحقلين التاليين من كائن transactions (أو unconfirmed_transactions):

tx_hash — تجزئة المعاملة (مجموع اختباري لمحتوى الطلب أو الحدث).
bc_uniq_key — معرّف حدث فريد داخل المعاملة، يُقدّمه مرسل الـ webhook.

خوارزمية التحقق:

1. قبل معالجة الـ webhook، تحقّق من أن توليفة hash + uniq_key لم تتم معالجتها من قبل وليست مخزّنة في نظامك.
2. إذا كان الحدث موجودًا بالفعل، فيجب تجاهله بوصفه نسخة مكرّرة.
3. إذا كان الحدث جديدًا، فقم بمعالجته وسجّله في قاعدة بياناتك.