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

وب‌هوک‌ها رویدادها را پس از وقوع به سرور شما می‌فرستند. آدرس وب‌هوک (اختیاری) را برای برنامه‌تان در بیشتر ← API پذیرنده ثبت کنید؛ از آن به بعد پلتفرم برای هر رویدادی که در آن مشترک شده‌اید یک بدنه‌ی JSON امضاشده POST می‌کند.

قالب پیام

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

update_id در ارسال‌های دوباره‌ی یک رویداد ثابت می‌ماند — حذف تکراری‌ها را بر پایه‌ی همان انجام دهید. request_date (زمان UTC با قالب ISO 8601 و دقت میکروثانیه) برای هر تلاش ارسال به‌طور جداگانه ثبت می‌شود. payload شیء کامل همان نوع رویداد است: شیء صورت‌حساب برای رویدادهای صورت‌حساب، شیء چک، انتقال یا اشتراک (ساختار هرکدام در صفحه‌ی متدهای آن آمده است: صورت‌حساب‌ها، انتقال‌ها و چک‌ها، اشتراک‌ها).

انواع رویداد

update_type	زمان ارسال	محتوا
invoice_paid	صورت‌حسابی پرداخت می‌شود — فعال‌سازی جداگانه لازم نیست	شیء صورت‌حساب
invoice_expired	مهلت صورت‌حسابی بدون پرداخت تمام می‌شود	شیء صورت‌حساب
check_activated	چک یا سهم یکی از گیرندگان دریافت می‌شود	شیء چک؛ دریافت سهم فهرست‌شده activated_slot هم دارد
check_expired	چک با فهرست گیرندگان منقضی می‌شود و سهم‌های دریافت‌نشده به برنامه برگردانده می‌شوند	شیء چک با status: "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 دارد: محتوای یک انتقال معمولی اصلاً فیلد kind ندارد؛ پس محتوایی را که kind: "withdrawal" دارد پرداخت روی شبکه و محتوای بدون 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"])

بررسی را روی بایت‌های خام دریافتی انجام دهید — چیزی که دوباره سریالایز شده می‌تواند بایت‌به‌بایت فرق داشته باشد و در بررسی رد شود. فقط توکن اصلی امضا می‌کند؛ توکن‌های محدود هرگز. تعویض توکن اصلی کلید امضای وب‌هوک را بی‌درنگ تغییر می‌دهد، پس هم‌زمان کلید محرمانه‌ی روی سرورتان را هم به‌روز کنید.

ارسال و تلاش دوباره

• ارسال وقتی موفق حساب می‌شود که ظرف 10 ثانیه پاسخ 2xx برسد. سریع پاسخ دهید و کار طولانی را جداگانه پردازش کنید. تغییر مسیر (redirect) دنبال نمی‌شود: پاسخ 3xx ناموفق حساب می‌شود، پس نشانی نهایی را ثبت کنید.

• خطا، پایان زمان انتظار یا قطع اتصال باعث تلاش دوباره می‌شود: حداکثر 17 بار، با فاصله‌ای که از 10 ثانیه شروع می‌شود و تا 8 ساعت دو برابر می‌شود (با کمی پراکندگی تصادفی)، روی هم حدود 3 روز. تحویل تضمین‌شده نیست؛ پس از اختلال از getInvoices برای تطبیق پرداخت‌ها استفاده کنید.

• هر تلاش به آدرس وب‌هوکی می‌رود که در همان لحظه ذخیره شده است: اگر آدرس را عوض کنید، تلاش‌های در انتظار به آدرس جدید می‌روند و اگر آن را حذف کنید، این تلاش‌ها کنار گذاشته می‌شوند.

• پس از آخرین تلاش، آن ارسال رها می‌شود. خود آدرس وب‌هوک هیچ‌وقت خودکار غیرفعال نمی‌شود — اختلال در سرور دریافت‌کننده باعث لغو خودکار اشتراک برنامه‌ی شما در رویدادها نمی‌شود.

• چون تلاش دوباره در کار است، هندلر شما باید در برابر تکرار امن باشد: پیش از هر اقدامی تکراری‌ها را بر پایه‌ی update_id حذف کنید.

⚠️ پیش از انجام سفارش، بررسی کنید

هر کسی می‌تواند به آدرس وب‌هوک شما POST بزند. تا وقتی بررسی امضا موفق نشده، بدنه را ورودی غیرقابل‌اعتماد بدانید: سفارشی نفرستید، حساب کسی را شارژ نکنید، چیزی را پرداخت‌شده علامت نزنید. ترتیب امن این است: بررسی امضا ← حذف تکراری‌ها بر پایه‌ی update_id ← اقدام.