API reference: webhooks

Event hone ke baad webhooks use aapke server par bhejte hain. More → Merchant API mein app ka Webhook URL (optional) set karein; phir platform har subscribed event ke liye signed JSON body POST karta hai.

Envelope

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

Ek hi event ki redelivery par update_id wahi rahta hai — duplicates rokne ke liye ise key banaayein. request_date har delivery attempt par set hota hai. payload event type ka poora object hai: invoice events ke liye invoice object, ya check, transfer ya subscription object (formats sambandhit reference pages par hain).

Event types

update_type	Kab aata hai	Payload
invoice_paid	Invoice pay ho — alag opt-in zaroori nahi	Invoice object
invoice_expired	Unpaid invoice ki deadline guzar jaaye	Invoice object
check_activated	Check ya ek recipient ka hissa claim ho	Check object; named-list claim mein activated_slot bhi
check_expired	Named-list check expire ho aur unclaimed shares app mein waapas aayein	recipients aur unke claimed_at ke saath check object
transfer_completed	Transfer complete ho ya on-chain payout confirm ho	Transfer ya withdrawal object
transfer_returned	Unclaimed pending transfer app mein waapas aaye, ya on-chain payout fail ho aur hold waapas mile	Transfer ya withdrawal object
refund_completed	Refund execute ho	refunded_* fields waala invoice object
subscription_activated	User plan approve kare	Subscription object
subscription_charged	Period ka payment collect ho — charge.kind bataata hai: initial, renewal ya resubscribe	Subscription object + charge: {period_no, kind, asset, amount, fee, paid_at}
subscription_cancelled	Koi bhi taraf subscription cancel kare	Subscription object
subscription_expired	Grace period bina payment ke khatam ho	Subscription object

App mein banaaye on-chain payouts bhi yahi transfer events use karte hain. Unke payload mein kind: "withdrawal", network, address aur txid jaise chain fields, aur completed ya failed status hota hai. Unka transfer_id alag ID sequence ka hai; use karne se pehle kind se payload type pehchaanein. Downloadable OpenAPI reference dono payload variants bataata hai.

invoice_paid ke alaawa sab opt-in hain (Crypto Bot se aage ka extension — sirf Crypto Bot format handle karne waale client ko unknown update_type tabhi milega jab aap use chunein). Har app ke Webhook section mein Extra webhook events se opt in karein — toggles upar table ke identifiers use karte hain. Events lene ke liye webhook URL save karein.

Signature verify karna

Har delivery ke saath TgPayCrypto-API-Signature header aata hai (TgCryptoPay-API-Signature aur Crypto-Pay-API-Signature usi value wale compatibility aliases hain): 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["TgPayCrypto-API-Signature"])

Verification request mein mile raw bytes par karein — JSON parse karke dobara serialize karne par bytes badal sakte hain aur check fail ho sakta hai. 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

• Attempt timeout hone se pehle 2xx response mile to delivery successful maani jaati hai. Jaldi respond karein aur lambe tasks alag process karein.
• Error status, timeout ya connection failure par badhte delay ke saath retries hoti hain, platform ki attempt limit tak. Delivery guaranteed nahi hai; outage ke baad getInvoices se payments milaayein.
• Aakhri attempt ke baad delivery drop ho jaati hai. Webhook URL apne aap kabhi disable nahi hota — unstable endpoint ki wajah se app chupchaap unsubscribe nahi hota.
• Retries hoti hain, isliye handler idempotent hona chahiye: action lene se pehle update_id se duplicates rokein.

⚠️ 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.