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

يدفع الويب هوك الأحداث إلى خادمك لحظة وقوعها. اضبط رابط الويب هوك لتطبيقك في المزيد ← واجهة التجار؛ عندها ترسل المنصة جسم 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	عند استلام أحد شيكاتك	كائن الشيك
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	عند انقضاء مهلة السماح دون دفع	كائن الاشتراك

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

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

يحمل كل تسليم الترويسة TgPayCrypto-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 خلال 10 ثوانٍ.
• وأي شيء آخر — حالة خطأ أو انتهاء مهلة أو فشل اتصال — تُعاد محاولته بفواصل متضاعفة: المحاولة الأولى بعد نحو 10 ثوانٍ، ثم تتضاعف الفترة حتى 8 ساعات، وحتى 17 محاولة موزّعة على 3 أيام تقريبًا.
• وبعد آخر محاولة يُسقط التسليم. أما رابط الويب هوك نفسه فلا يُعطَّل تلقائيًا أبدًا — فتعثّره المتقطع لا يُلغي اشتراك تطبيقك في صمت.
• ولأن إعادة المحاولة واقعة لا محالة، فيجب أن يحتمل معالجك التكرار: استبعد المكرّر اعتمادًا على update_id قبل أي إجراء.

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

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