API reference: webhooks

Webhooks har event ko hote hi aapke server par push kar dete hain. Apne app par More → Merchant API mein Webhook URL set karein; uske baad platform har us event ke liye ek signed JSON body POST karta hai jiske liye aapne subscribe kiya hai.

Envelope

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

Ek hi event ki har redelivery par update_id wahi rehta hai — apni deduplication usi par karein. request_date har delivery attempt par stamp hota hai. payload us event type ka poora object hota hai: invoice events ke liye invoice object, check object, ya subscription object (shapes apne-apne reference pages par).

Event types

update_type	Kab fire hota hai	Payload
invoice_paid	koi invoice pay ho jaaye — hamesha deliver hota hai	invoice object
invoice_expired	koi invoice bina pay hue apni deadline paar kar jaaye	invoice object
check_activated	aapke kisi check ko claim kiya jaaye	check object
refund_completed	koi refund execute ho	refunded_* fields ke saath invoice object
subscription_activated	koi user plan approve kare	subscription object
subscription_charged	kisi period ka bill bane — charge.kind batata hai kaunsa: initial, renewal, ya resubscribe	subscription object + charge: {period_no, kind, asset, amount, fee, paid_at}
subscription_cancelled	kisi bhi taraf se subscription cancel ho	subscription object
subscription_expired	grace period bina pay hue khatam ho jaaye	subscription object

invoice_paid ke alawa sab kuch opt-in hai (Crypto Bot ke upar ek extension — strict Crypto Bot-shaped consumer ko kabhi koi anjaan update_type nahi milta, jab tak aap khud na maangein). Per app opt-in Merchant API screen par Extra webhook events ke neeche hota hai — toggles webhook URL set hote hi dikhte hain, aur unpar upar wali table ke raw identifiers hi likhe hote hain.

Signature verify karna

Har delivery ke saath TgCryptoPay-API-Signature header aata hai (Crypto-Pay-API-Signature usi value wala compatibility alias hai): raw request body ka hex HMAC-SHA256, jiski key aapke app ke main API token ka SHA-256 digest hai. Yeh Crypto Bot ka hi scheme hai, isliye maujooda verification code bina badle kaam karta hai:

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

Verification raw mile hue bytes par karein — dobara serialize kiya gaya parse byte-for-byte alag ho sakta hai aur check fail kar dega. Sirf main token sign karta hai; restricted tokens kabhi nahi. Main token rotate karte hi webhook signing ki key turant badal jaati hai, isliye usi ke saath apne server par secret bhi update karein.

Delivery aur retries

• Koi delivery 10 seconds ke andar mile kisi bhi 2xx response par successful maani jaati hai.
• Iske alawa kuch bhi — error status, timeout, connection failure — exponential backoff ke saath retry hota hai: pehla retry lagbhag 10 seconds baad, gap har baar dugna hote hue 8 hours tak, kul 17 attempts tak jo lagbhag 3 din mein phaile hote hain.
• Aakhri attempt ke baad delivery drop kar di jaati hai. Webhook URL khud kabhi apne aap disable nahi hota — koi kharab endpoint aapke app ko chupchaap unsubscribe nahi karta.
• Kyunki retries hote hain, aapka handler idempotent hona zaroori hai: kuch bhi karne se pehle update_id par dedupe karein.

⚠️ Poora karne se pehle verify karein

Aapke webhook URL par koi bhi POST kar sakta hai. Jab tak signature check pass na ho, body ko untrusted input maanein: na koi order ship karein, na kisi user ko credit karein, na kuch paid mark karein. Safe order yeh hai: signature verify karein → update_id par dedupe karein → phir kuch karein.