مرجع الواجهة: الويب هوك

يرسل الويب هوك الأحداث إلى خادمك بعد وقوعها. اضبط رابط الويب هوك (اختياري) لتطبيقك في المزيد ← واجهة التجار؛ عندها ترسل المنصة جسم JSON موقّعًا عبر POST لكل حدث أنت مشترك فيه.

بنية الرسالة

{
  "update_id": 123,
  "update_type": "invoice_paid",
  "request_date": "2026-08-11T12:00:00Z",
  "payload": { … }
}

يبقى update_id ثابتًا عبر عمليات إعادة تسليم الحدث نفسه — فاعتمد عليه في استبعاد المكرّر. ويُسجَّل request_date مع كل محاولة تسليم. أما payload فهو الكائن الكامل الخاص بنوع الحدث: كائن الفاتورة لأحداث الفواتير، أو كائن الشيك، أو كائن التحويل، أو كائن الاشتراك (وأشكالها في صفحات المرجع المقابلة).

أنواع الأحداث

update_type	متى ينطلق	الحمولة
invoice_paid	عند دفع فاتورة — لا يحتاج إلى تفعيل منفصل	كائن الفاتورة
invoice_expired	عند انقضاء أجل فاتورة دون دفع	كائن الفاتورة
check_activated	عند استلام شيك أو حصة أحد المستلمين	كائن الشيك؛ ويضاف activated_slot عند استلام حصة من قائمة مستلمين
check_expired	عند انتهاء شيك مخصص لقائمة وعودة الحصص غير المستلمة إلى التطبيق	كائن الشيك مع recipients وقيم claimed_at لهم
transfer_completed	عند اكتمال تحويل أو تأكيد دفعة صادرة على الشبكة	كائن التحويل أو السحب
transfer_returned	عند عودة تحويل معلّق غير مستلم إلى التطبيق، أو فشل دفعة صادرة على الشبكة وإعادة المبلغ المحجوز	كائن التحويل أو السحب
refund_completed	عند تنفيذ استرداد	كائن الفاتورة مع حقول refunded_*
subscription_activated	عند موافقة مستخدم على خطة	كائن الاشتراك
subscription_charged	عند تحصيل فترة — و charge.kind يبيّن نوعها: initial أو renewal أو resubscribe	كائن الاشتراك مع charge: {period_no, kind, asset, amount, fee, paid_at}
subscription_cancelled	عند إلغاء اشتراك من أي من الطرفين	كائن الاشتراك
subscription_expired	عند انقضاء مهلة السماح دون دفع	كائن الاشتراك

تستخدم المدفوعات الصادرة على الشبكة التي تنشئها داخل التطبيق أحداث التحويل نفسها. تتضمن حمولتها kind: "withdrawal"، وحقول الشبكة مثل network وaddress وtxid، والحالة completed أو failed. ويأتي transfer_id الخاص بها من تسلسل معرّفات مستقل؛ لذا ميّز الحمولات باستخدام kind قبل الاعتماد عليه. يصف مرجع OpenAPI القابل للتنزيل كلا نوعي الحمولة.

وكل ما عدا invoice_paid اختياري (وهو امتداد يتجاوز Crypto Bot — فالتكامل المصمَّم لواجهة Crypto Bot لا يستقبل نوع update_type غير معروف لديه ما لم تفعّله أنت). والاشتراك يجري لكل تطبيق على حدة تحت أحداث ويب هوك إضافية في قسم الويب هوك الخاص بالتطبيق. تستخدم المفاتيح المعرّفات الواردة في الجدول أعلاه. احفظ رابط ويب هوك لاستقبال الأحداث.

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

يحمل كل تسليم الترويسة TgPayCrypto-API-Signature (و TgCryptoPay-API-Signature و Crypto-Pay-API-Signature اسمان بديلان متوافقان بالقيمة نفسها): وهي HMAC-SHA256 بالنظام الست عشري على جسم الطلب الخام، بمفتاح هو خلاصة SHA-256 لـرمز API الرئيسي لتطبيقك. وهي آلية Crypto Bot نفسها، فتعمل شيفرة التحقق القائمة لديك دون تعديل:

import hashlib, hmac

secret = hashlib.sha256(API_TOKEN.encode()).digest()
expected = hmac.new(secret, raw_body, hashlib.sha256).hexdigest()
ok = hmac.compare_digest(expected, headers["TgPayCrypto-API-Signature"])

تحقّق من التوقيع على البايتات الخام كما وصلت — فإعادة ترميز نتيجة التحليل قد تختلف بايتًا ببايت فيسقط الفحص. والرمز الرئيسي وحده يوقّع؛ أما الرموز المحدودة فلا توقّع أبدًا. وتدوير الرمز الرئيسي يغيّر مفتاح توقيع الويب هوك فورًا، فحدِّث السر على خادمك في اللحظة نفسها.

التسليم وإعادة المحاولة

• يُعدّ التسليم ناجحًا عند استلام استجابة 2xx قبل انتهاء مهلة المحاولة. أرسل الاستجابة سريعًا، ونفّذ المهام الطويلة بشكل منفصل.
• تؤدي حالة الخطأ أو انتهاء المهلة أو فشل الاتصال إلى إعادة المحاولة بفواصل متزايدة، حتى الحد الذي تحدده المنصة. التسليم غير مضمون؛ استخدم getInvoices لمطابقة المدفوعات بعد انقطاع الخدمة.
• وبعد آخر محاولة يُسقط التسليم. أما رابط الويب هوك نفسه فلا يُعطَّل تلقائيًا أبدًا — فتعثّره المتقطع لا يُلغي اشتراك تطبيقك في صمت.
• ولأن التسليم قد يُعاد، فيجب أن يحتمل معالجك التكرار: استبعد المكرّر اعتمادًا على update_id قبل أي إجراء.

⚠️ تحقّق قبل التنفيذ

يستطيع أي أحد أن يرسل POST إلى رابط الويب هوك لديك. وإلى أن يجتاز التوقيع الفحص، عامل الجسم كمدخل غير موثوق: لا تشحن طلبًا، ولا تضف رصيدًا لمستخدم، ولا تعُدَّ شيئًا مدفوعًا. والترتيب الآمن هو: التحقق من التوقيع ← استبعاد المكرّر اعتمادًا على update_id ← التنفيذ.