API maʼlumotnomasi: webhooklar

Webhooklar hodisalarni sodir boʻlgan zahoti serveringizga yetkazadi. Ilovangizga Yana → Merchant API boʻlimida Webhook URL manzilini belgilang — shundan keyin platforma siz obuna boʻlgan har bir hodisa uchun imzolangan JSON-tanani POST qiladi.

Konvert

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

update_id bitta hodisaning qayta yetkazishlarida oʻzgarmaydi — dedublikatsiyani shunga quring. request_date har bir yetkazish urinishida qoʻyiladi. payload — hodisa turiga mos toʻliq obyekt: invoys hodisalari uchun invoys obyekti, chek obyekti yoki obuna obyekti (ularning tarkibi — tegishli maʼlumotnoma sahifalarida).

Hodisa turlari

update_type	Qachon yuboriladi	Payload
invoice_paid	invoys toʻlanganda — har doim yetkaziladi	invoys obyekti
invoice_expired	invoys toʻlanmasdan muddati oʻtganda	invoys obyekti
check_activated	cheklaringizdan biri faollashtirilganda	chek obyekti
refund_completed	qaytarish bajarilganda	refunded_* maydonlari bilan invoys obyekti
subscription_activated	foydalanuvchi tarifni tasdiqlaganda	obuna obyekti
subscription_charged	davr uchun pul yechilganda — qaysi biri ekanini charge.kind aytadi: initial, renewal yoki resubscribe	obuna obyekti + charge: {period_no, kind, asset, amount, fee, paid_at}
subscription_cancelled	obunani ikki tomondan biri bekor qilganda	obuna obyekti
subscription_expired	imtiyoz davri toʻlovsiz tugaganda	obuna obyekti

invoice_paid hodisasidan tashqari hammasi ixtiyoriy ravishda yoqiladi (Crypto Bot ustidagi kengaytma — qatʼiy Crypto Bot shakliga moʻljallangan isteʼmolchi oʻzi soʻramasa, notanish update_type bilan hech qachon toʻqnashmaydi). Har bir ilova uchun obuna Merchant API ekranidagi ilova kartochkasida, Qoʻshimcha webhook hodisalari blokida yoqiladi: tugmachalar Webhook URL belgilangandan keyin paydo boʻladi va yuqoridagi jadvaldagi xom identifikatorlar bilan nomlangan.

Imzoni tekshirish

Har bir yetkazish TgPayCrypto-API-Signature sarlavhasini olib keladi (Crypto-Pay-API-Signature — xuddi shu qiymatga ega, moslik uchun muqobil nom): xom soʻrov tanasidan olingan HMAC-SHA256 ning hex qiymati, kaliti — ilovangizning asosiy API tokeni SHA-256 dayjesti. Bu Crypto Bot sxemasi, shuning uchun mavjud tekshirish kodi oʻzgarishsiz ishlaydi:

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"])

Tekshirishni qabul qilingan xom baytlar boʻyicha bajaring — qayta serializatsiya qilingan natija baytma-bayt farq qilishi va tekshiruvdan oʻtmasligi mumkin. Faqat asosiy token imzolaydi; cheklangan tokenlar hech qachon imzolamaydi. Asosiy tokenni yangilash webhook imzosining kalitini bir zumda almashtiradi — shuning uchun serveringizdagi sirni ham oʻsha zahoti yangilang.

Yetkazish va qayta urinishlar

• Yetkazish 10 soniya ichida kelgan istalgan 2xx javob bilan muvaffaqiyatli hisoblanadi.
• Qolgan hammasi — xato status, taymaut, ulanishning uzilishi — eksponensial kechikish bilan takrorlanadi: birinchi qayta urinish taxminan 10 soniyadan keyin, oraliq 8 soatgacha ikkilanib boradi, jami 17 tagacha urinish taxminan 3 kunga taqsimlanadi.
• Oxirgi urinishdan keyin yetkazish tashlab yuboriladi. Webhook manzilining oʻzi hech qachon avtomatik oʻchirilmaydi — ishonchsiz endpoint ilovangizni sekingina obunadan chiqarib yubormaydi.
• Qayta urinishlar boʻlgani uchun ishlov beruvchingiz idempotent boʻlishi shart: harakat qilishdan oldin update_id boʻyicha dedublikatsiya qiling.

⚠️ Bajarishdan oldin tekshiring

Sizning webhook manzilingizga POST yuborish har kimning qoʻlidan keladi. Imzo tekshiruvi oʻtmaguncha tanani ishonchsiz kiruvchi maʼlumot deb biling: buyurtmani joʻnatmang, foydalanuvchiga pul yozmang, hech narsani toʻlangan deb belgilamang. Xavfsiz tartib: imzoni tekshirish → update_id boʻyicha dedublikatsiya → harakat.