مرجع API: وب‌هوک‌ها

وب‌هوک‌ها رویدادها را پس از وقوع به سرور شما می‌فرستند. آدرس وب‌هوک (اختیاری) را برای برنامه‌تان در بیشتر ← API پذیرنده ثبت کنید؛ از آن به بعد پلتفرم برای هر رویدادی که در آن مشترک شده‌اید یک بدنه‌ی 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 نام‌های جایگزینی برای سازگاری‌اند، با همان مقدار): مقدار hex از 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 ← اقدام.