مرجع 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	یکی از چک‌های شما دریافت می‌شود	شیء چک
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 ناشناخته برنمی‌خورد، مگر خودتان خواسته باشید). برای هر برنامه، زیر رویدادهای بیشتر وب‌هوک در صفحه‌ی API پذیرنده آن‌ها را فعال کنید — این کلیدها به‌محض ثبت آدرس وب‌هوک ظاهر می‌شوند و نام هرکدام همان شناسه‌ی خام جدول بالاست.

بررسی امضا

هر ارسال هدر 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["TgCryptoPay-API-Signature"])

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

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

• ارسال با هر پاسخ 2xx که ظرف 10 ثانیه برسد موفق حساب می‌شود.
• هر چیز دیگری — وضعیت خطا، تایم‌اوت، قطع اتصال — با فاصله‌های فزاینده دوباره فرستاده می‌شود: اولین تلاش دوباره حدود 10 ثانیه بعد، فاصله هر بار دو برابر می‌شود تا سقف 8 ساعت، در مجموع تا 17 تلاش در حدود 3 روز.
• پس از آخرین تلاش، آن ارسال رها می‌شود. خود آدرس وب‌هوک هیچ‌وقت خودکار غیرفعال نمی‌شود — نقطه‌ی پایانی ناپایدار، اشتراک برنامه‌ی شما را بی‌اطلاع لغو نمی‌کند.
• چون تلاش دوباره در کار است، هندلر شما باید در برابر تکرار امن باشد: پیش از هر اقدامی تکراری‌ها را بر پایه‌ی update_id حذف کنید.

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

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