अपने स्वयं के एप्लिकेशन में हस्ताक्षरित HTTP अनुरोधों के रूप में TicketWave इवेंट प्राप्त करें।

वेबहुक्स

एक वेबहुक एक HTTP अनुरोध है जिसे TicketWave आपको भेजता है। जब भी आपके सर्वर पर कुछ होता है — कोई टिकट खुलता है, कोई सदस्य ब्लैकलिस्ट हो जाता है — TicketWave आपके स्वामित्व वाले URL पर एक JSON बॉडी POST करता है।

यही Log Channels से इसका अंतर है: लॉग चैनल Discord में एक एम्बेड लिखते हैं ताकि इंसान उसे पढ़ सकें, जबकि वेबहुक्स कच्चा इवेंट आपके कोड को सौंप देते हैं।

वेबहुक्स एक प्रीमियम फीचर हैं। प्रीमियम के बिना, एंडपॉइंट बनाए नहीं जा सकते और कोई इवेंट डिलीवर नहीं होता।

एक एंडपॉइंट बनाएं

एंडपॉइंट्स पेज खोलें

सर्वर डैशबोर्ड → Webhooks → Endpoints।

एक एंडपॉइंट जोड़ें

Add Endpoint पर क्लिक करें और दो फ़ील्ड भरें:

Field	Description
Endpoint URL	वह `https://` URL जो अनुरोध प्राप्त करता है
Event Types	इस एंडपॉइंट को कौन-कौन से इवेंट मिलने चाहिए

एक एंडपॉइंट केवल वही प्रकार प्राप्त करता है जिन्हें आप चुनते हैं। कोई भी न चुनना अनुमति नहीं है — कम से कम एक चुनें।

साइनिंग सीक्रेट कॉपी करें

TicketWave एंडपॉइंट बनते ही एक साइनिंग सीक्रेट (whsec_…) जनरेट करता है। एंडपॉइंट्स की सूची खोलें, आई आइकन से उसे दिखाएँ और अपनी एप्लिकेशन की कॉन्फ़िगरेशन में कॉपी करें।

सीक्रेट को पासवर्ड की तरह संभालें। जिसके पास यह होगा, वह ऐसे अनुरोध बना सकता है जो आपकी सिग्नेचर जाँच पास कर लें। इसे environment variable में रखें, कभी भी अपने repository में नहीं।

एक टेस्ट इवेंट भेजें

एंडपॉइंट पंक्ति पर Send test event बटन (पेपर प्लेन) का उपयोग करें। यह एक वास्तविक, पूरी तरह साइन किया हुआ अनुरोध भेजता है, जिसके payload में "test": true होता है, ताकि आप असली टिकट उस पर निर्भर होने से पहले पुष्टि कर सकें कि आपका receiver काम कर रहा है।

परिणाम Webhooks history में किसी भी अन्य delivery की तरह दिखाई देता है।

एंडपॉइंट आवश्यकताएँ

Requirement	Detail
Scheme	केवल `https://` — `http://` अस्वीकार किया जाता है
Host	सार्वजनिक रूप से resolvable होना चाहिए। private, loopback, link-local और CGNAT addresses अस्वीकार किए जाते हैं
Response	कोई भी `2xx` status सफलता माना जाता है
Timeout	जवाब देने के लिए आपके पास 10 seconds हैं
Redirects	follow नहीं किए जाते। `3xx` failure माना जाता है
Limit	प्रति server अधिकतम 5 endpoints

Host जाँच तब भी होती है जब आप endpoint सेव करते हैं और हर एक delivery से पहले भी, इसलिए यदि कोई domain बाद में internal address पर resolve होने लगे, तो उसे delivery मिलना बंद हो जाता है।

अनुरोध

हर delivery एक JSON body के साथ POST होती है।

Headers

Header	Example	Meaning
`Content-Type`	`application/json`	हमेशा JSON
`User-Agent`	`TicketWave-Webhooks/1.0.5`	भेजने वाले bot का version
`X-TicketWave-Event`	`ticket.created`	इवेंट प्रकार
`X-TicketWave-Delivery`	`wh_3f2a…`	इस delivery का unique id
`X-TicketWave-Timestamp`	`1786224191`	Unix seconds, signature का हिस्सा
`X-TicketWave-Signature`	`sha256=9f86d0…`	अनुरोध का HMAC

Body

हर payload एक ही envelope का उपयोग करता है। केवल data हर event type के अनुसार बदलता है:

{
  "event": "ticket.created",
  "timestamp": "2026-08-26T08:23:11.000Z",
  "guild_id": "123456789012345678",
  "data": {
    "ticket_id": "ticket-1042",
    "ticket_num_id": 1042,
    "channel_id": "998877665544332211",
    "category": "🤖 Support",
    "user": { "id": "987654321098765432", "username": "Luna" },
    "created_at": "2026-08-26T08:23:11.000Z"
  }
}

हर type के data object के लिए Event Reference देखें।

सिग्नेचर सत्यापित करना

जो भी आपका endpoint URL जान लेता है, वह उस पर POST अनुरोध भेज सकता है। सिग्नेचर ही आपको असली TicketWave delivery और नकली delivery में फर्क करने देता है।

हमेशा सत्यापित करें। एक असत्यापित endpoint जो आपके सिस्टम में चीज़ें बनाता या बंद करता है, खुला दरवाज़ा है।

सिग्नेचर कैसे बनाया जाता है

TicketWave timestamp और raw request body को एक dot के साथ जोड़ता है, और आपके endpoint secret का उपयोग करके उस परिणाम पर HMAC-SHA256 चलाता है:

signed_payload = X-TicketWave-Timestamp + "." + raw_request_body
signature      = HMAC_SHA256(signed_payload, your_endpoint_secret)

Header यह digest hex-encoded और prefixed रूप में ले जाता है: sha256=<digest>।

आपके receiver को क्या करना चाहिए

Raw body पढ़ें। ठीक उन्हीं bytes के विरुद्ध सत्यापित करें जो आपको प्राप्त हुए हैं। यदि आपका framework पहले JSON parse करता है और आप उसे फिर से serialize करते हैं, तो key order या spacing बदल सकती है और digest मेल नहीं खाएगा।

HMAC को फिर से गणना करें timestamp + "." + rawBody पर, अपने secret के साथ।

Constant time में तुलना करें (crypto.timingSafeEqual Node में)। साधारण === timing information लीक करता है।

Timestamp जाँचें कि वह हाल का है — पाँच मिनट की tolerance एक अच्छा default है। Timestamp signed payload के अंदर होता है, इसलिए attacker पुराने request को नए timestamp के साथ replay नहीं कर सकता।

एक पूर्ण implementation Example Server पेज पर उपलब्ध है।

Retries

जो delivery fail होती है, उसे अपने आप retry किया जाता है।


Attempts	3 (पहला प्रयास + 2 retries)
Backoff	1 second, फिर 5 seconds
Retried on	Network errors, timeouts, `408`, `429` और कोई भी `5xx`
Not retried on	बाकी सभी `4xx` — इसका मतलब है कि आपके endpoint ने जानबूझकर अनुरोध अस्वीकार किया

Retries की वजह से आपका endpoint एक ही इवेंट दो बार प्राप्त कर सकता है। X-TicketWave-Delivery को idempotency key की तरह उपयोग करें: जिन ids को आप process कर चुके हैं, उन्हें याद रखें और दोहराव को अनदेखा करें।

Deliveries क्रम में नहीं होतीं। यदि दो tickets एक ही समय पर बनाए जाते हैं, तो अनुरोध किसी भी क्रम में आ सकते हैं — यदि order आपके लिए महत्वपूर्ण है, तो body के timestamp field का उपयोग करें।

Delivery History

डैशबोर्ड का Webhooks पेज हर delivery को उसके status, response code, duration और attempts की संख्या के साथ सूचीबद्ध करता है। किसी row को खोलकर वह exact request payload देखें जो भेजा गया था और वह response देखें जो आपके server ने लौटाया।

Failed deliveries को detail page से Retry Webhook के साथ फिर से भेजा जा सकता है। यह original payload को उसी endpoint पर फिर से भेजता है और एक नई delivery रिकॉर्ड करता है।

History 30 days तक रखी जाती है, फिर अपने आप साफ़ कर दी जाती है।

समस्या निवारण

Problem	Fix
Endpoint सेव नहीं किया जा सकता	URL `https://` होना चाहिए और public address पर resolve होना चाहिए
सब कुछ बिना response code के failed दिखता है	अनुरोध आप तक पहुँचा ही नहीं — timeout, DNS failure या connection refused
Signature कभी match नहीं होती	आप parsed body को hash कर रहे हैं, raw bytes को नहीं, या `timestamp + "."` prefix भूल गए हैं
कुछ समय बाद deliveries रुक जाती हैं	जाँचें कि क्या आपका host `4xx` लौटाना शुरू कर चुका है — उन पर retry नहीं होता
कोई इवेंट कभी नहीं आता	Endpoint उस type के लिए subscribed नहीं है, या server ने premium खो दिया है
Duplicate events	retries पर अपेक्षित — `X-TicketWave-Delivery` पर deduplicate करें

अगले कदम

Event Reference (हर इवेंट और उसका payload)
Example Server (एक चलने योग्य Express receiver)
Log Channels (वही इवेंट्स, लेकिन Discord में पोस्ट किए गए)

अवलोकन