Webhook नोटिफ़िकेशन

अपने ऐप्लिकेशन में QR कोड डिलीवरी और रिन्यूअल के नतीजे पाने के लिए Webhooks का इस्तेमाल करें।

Webhook क्या है?

iRoamly QR कोड डिलीवरी और रिन्यूअल के नतीजों के लिए Webhook सूचनाएँ भेजता है। हर Webhook HTTPS का इस्तेमाल करता है और उसमें JSON पेलोड होता है। Webhooks का इस्तेमाल इनके लिए करें:

• रिडेम्पशन कोड कन्वर्ट होने या सीधी QR कोड खरीद पूरी होने के बाद QR कोड की जानकारी प्राप्त करें।
• Webhook के ज़रिए रिन्यूअल के परिणाम प्राप्त करें: रिन्यूअल QR कोड तैयार होने पर esim.renewal.success, अपस्ट्रीम रिन्यूअल ऑर्डर विफल होने पर esim.renewal.failed।

अगर आपका एंडपॉइंट 2xx स्टेटस के साथ जवाब नहीं देता, तो iRoamly कुल मिलाकर 5 बार तक डिलीवरी की कोशिश करता है: पहली तुरंत, फिर 30 सेकंड, 2 मिनट, 3 मिनट और 5 मिनट बाद दोबारा।

Webhook प्राप्त करने के चरण

इन चरणों से आप अपने ऐप में रियल-टाइम इवेंट प्राप्त करना शुरू कर सकते हैं:

• अनुरोध प्राप्त करने के लिए एक लोकल एंडपॉइंट बनाएँ
• iRoamly Shop डैशबोर्ड में डेवलपर > Webhook नोटिफ़िकेशन के अंतर्गत अपना Webhook एंडपॉइंट रजिस्टर करें

1. अनुरोध प्राप्त करने के लिए एक लोकल एंडपॉइंट बनाएँ

अपने लोकल ऐप्लिकेशन में, एक नया रूट बनाएँ जो POST अनुरोध स्वीकार कर सके।

उदाहरण के लिए, आप Next.js पर एक API रूट जोड़ सकते हैं:

import type { NextApiRequest, NextApiResponse } from 'next';

export default (req: NextApiRequest, res: NextApiResponse) => {
  if (req.method === 'POST') {
    const payload = req.body;
    console.log(payload);
    res.status(200);
  }
};

इवेंट मिलने पर, iRoamly को यह बताने के लिए कि इवेंट सफलतापूर्वक डिलीवर हो गया, आपको HTTP 200 OK के साथ जवाब देना चाहिए।

2. अपना डेवलपमेंट Webhook एंडपॉइंट रजिस्टर करें

iRoamly Shop डैशबोर्ड में अपना सार्वजनिक रूप से एक्सेस किया जा सकने वाला HTTPS URL रजिस्टर करें।

आप ngrok जैसे टूल से अपने localhost सर्वर तक एक टनल बना सकते हैं।

3. जाँचें कि आपका Webhook एंडपॉइंट ठीक से काम कर रहा है

यह जाँचने के लिए कि आपके Webhook एंडपॉइंट को इवेंट मिल रहा है, कोई टेस्ट रिडेम्पशन कोड QR कोड में कन्वर्ट करें या सीधे QR कोड खरीदें।

सपोर्टेड इवेंट प्रकारों और उनके पेलोड की सूची।

डिलीवरी

हर इवेंट एक ही तरीके से डिलीवर होता है: इवेंट को सब्सक्राइब करने वाले हर एंडपॉइंट पर JSON बॉडी के साथ एक POST अनुरोध। कोई भी 2xx रिस्पॉन्स डिलीवर माना जाता है; अन्यथा दोबारा कोशिश की जाती है, कुल मिलाकर 5 बार तक (पहली तुरंत, फिर 30 सेकंड, 2 मिनट, 3 मिनट और 5 मिनट बाद दोबारा)। हर अनुरोध में ये हेडर होते हैं:

सिग्नेचर जाँचने का तरीका जानने के लिए Webhook अनुरोध सत्यापित करें देखें।

esim.qrcode

eSIM QR कोड से जुड़ी जानकारी, जो eSIM QR कोड रिडीम करने या खरीदने के बाद लौटाई जाती है।

नमूना अनुरोध बॉडी

{
	"code": 0,
	"data": {
		"activation_code": "CD112885573C49DDA42F64C905B925F4",
		"code": "UtTpoKCe769u2tt",
		"create_at": "2025-09-01 11:34:30",
		"isrenew": 0,
		"order_id": "ESIM202509021134343282",
		"plan_name": "Japan-eSIM-3GB-15 Days-Daily",
		"qrcode": "https://www.iroamly.com/qrcode/20250901/xSQfryvOWo0QUhsGcbpeTm9wWYfGu9BQ.png",
		"qrcode_content": "LPA:1$rsp1.cmlink.com$CD352885573C49DDA42F64C905B925F4",
		"sm_dp_address": "rsp1.cmlink.com"
	},
	"event_type": "esim.qrcode"
	}

रिन्यूअल सफल होने पर भेजा जाता है: अपस्ट्रीम प्रदाता के रिन्यूअल ऑर्डर का डाउनलोड विवरण लौटाते ही, सिस्टम रिन्यूअल कोड के लिए QR कोड जनरेट करता है और उसकी status 2 (रिडीम हो गया) हो जाती है।

अनुरोध हेडर

हर इवेंट की तरह, इस अनुरोध में भी X-Webhook-Delivery, X-Webhook-Timestamp, X-Webhook-Signature और X-Webhook-Signature-V2 होते हैं (इवेंट प्रकार देखें)।

नमूना अनुरोध बॉडी

{
	"code": 0,
	"data": {
		"activation_code": "CD112885573C49DDA42F64C905B925F4",
		"code": "RnB7xTq2Lm9pQaZ",
		"create_at": "2026-10-28 09:12:41",
		"download_url": "LPA:1$rsp1.cmlink.com$CD352885573C49DDA42F64C905B925F4",
		"iccid": "8944501234567890123",
		"iscouldrenewal": 1,
		"isrenew": 1,
		"plan_name": "Japan-eSIM-3GB-15 Days-Daily",
		"qrcode": "https://www.iroamly.com/qrcode/20261028/xSQfryvOWo0QUhsGcbpeTm9wWYfGu9BQ.png",
		"qrcode_content": "LPA:1$rsp1.cmlink.com$CD352885573C49DDA42F64C905B925F4",
		"renew_order_id": "TG202610280912410001",
		"renewal_father_code": "UtTpoKCe769u2tt",
		"sm_dp_address": "rsp1.cmlink.com"
	},
	"event_type": "esim.renewal.success"
}

फ़ील्ड

रिन्यूअल विफल होने पर भेजा जाता है: अपस्ट्रीम प्रदाता रिन्यूअल ऑर्डर का जवाब 0000 के अलावा किसी अन्य कोड से देता है, या प्रदाता को भेजा गया अनुरोध विफल हो जाता है।

(नोट: अपस्ट्रीम प्रदाता से कॉलबैक न आने या देर से आने पर यह इवेंट ट्रिगर नहीं होता। एक टाइमआउट सेट करें और कोड क्वेरी करने का विकल्प अपनाएँ — रिन्यूअल इवेंट संभालना देखें।)

अनुरोध हेडर

हर इवेंट की तरह, इस अनुरोध में भी X-Webhook-Delivery, X-Webhook-Timestamp, X-Webhook-Signature और X-Webhook-Signature-V2 होते हैं (इवेंट प्रकार देखें)।

नमूना अनुरोध बॉडी

{
	"code": -1,
	"data": {
		"code": "RnB7xTq2Lm9pQaZ",
		"create_at": "2026-10-28 09:12:41",
		"error_msg": "TuGe_RenewOrderEx RespCode: 9999",
		"isrenew": 1,
		"plan_name": "Japan-eSIM-3GB-15 Days-Daily",
		"renewal_father_code": "UtTpoKCe769u2tt"
	},
	"event_type": "esim.renewal.failed"
}

फ़ील्ड

रिन्यूअल अब esim.qrcode के रूप में डिलीवर नहीं होते; यह इवेंट QR कोड कन्वर्ज़न और सीधी QR कोड खरीद के लिए भेजा जाता है। esim.qrcode पेलोड की तुलना में:

• event_type और X-Webhook-Event हेडर esim.renewal.success या esim.renewal.failed होते हैं, और isrenew 1 होता है।
• data.code रिन्यूअल से बना नया रिडीम कोड है; जिस कोड को रिन्यू किया गया, वह data.renewal_father_code है।
• esim.renewal.success में renew_order_id, renewal_father_code, iscouldrenewal, download_url और iccid जुड़ते हैं, और इसमें order_id नहीं होता।
• विफल रिन्यूअल की सूचना esim.renewal.failed से दी जाती है, जिसमें शीर्ष-स्तरीय code -1 होता है और अपस्ट्रीम त्रुटि data.error_msg में होती है।

नए एंडपॉइंट डिफ़ॉल्ट रूप से तीनों इवेंट के लिए सब्सक्राइब होते हैं। मौजूदा एंडपॉइंट को esim.renewal.success और esim.renewal.failed अपने आप मिलते हैं — किसी बदलाव की ज़रूरत नहीं है।

• अपने हैंडलर को idempotent बनाएँ। दोबारा कोशिश में एक ही इवेंट एक से अधिक बार डिलीवर हो सकता है, इसलिए X-Webhook-Delivery या event_type + data.code के आधार पर डुप्लिकेट हटाएँ, और पहले से प्रोसेस किए गए इवेंट को अनदेखा करें।
• टाइमआउट का विकल्प रखें। अगर उचित समय के भीतर न esim.renewal.success आता है और न esim.renewal.failed, तो रिन्यूअल को विफल मानने के बजाय क्वेरी API (जैसे QR कोड क्वेरी करें) से कोड क्वेरी करें।
• रिफ़ंड तय करने के लिए esim.renewal.failed का इस्तेमाल न करें। यह केवल बताता है कि अपस्ट्रीम ऑर्डर विफल हुआ; क्रेडिट वापस होंगे या नहीं और कब, यह अलग से तय होता है, इसलिए इस इवेंट के आधार पर अपने ग्राहकों को रिफ़ंड न दें।

Webhook अनुरोधों पर iRoamly सिग्नेचर सत्यापित करें।

iRoamly सिग्नेचर कैसे सत्यापित करें?

iRoamly सिग्नेचर Webhook अनुरोध के X-Webhook-Signature हेडर में भेजा जाता है, sha256= के बाद hex-एन्कोडेड सिग्नेचर के रूप में। सिग्नेचर HMAC-SHA256 एल्गोरिदम से बनाया जाता है, जिसमें Webhook सीक्रेट कुंजी के रूप में और रॉ अनुरोध बॉडी (बिल्कुल जैसी मिली, किसी भी JSON पार्सिंग से पहले) संदेश के रूप में इस्तेमाल होती है।

नमूना Webhook हेडर

{
'X-Webhook-Signature': 'sha256=dd7bdd2cf1f6bac6e171c6c508c157b7cd3cc1fd196394277fb59ba0bdd9b87b'
}

आप अपना Webhook सीक्रेट डैशबोर्ड में डेवलपर > Webhook नोटिफ़िकेशन के अंतर्गत पा सकते हैं।

सिग्नेचर जनरेट करने के लिए, आप निम्नलिखित कोड स्निपेट का इस्तेमाल कर सकते हैं:

import * as crypto from 'crypto';

  generateSignature(payload: string, secret: string): string {
    const computedSignature = crypto
      .createHmac('sha256', secret)
      .update(payload)
      .digest('hex');
    return 'sha256=' + computedSignature;
  }

ऊपर दिए कोड स्निपेट में, payload रॉ अनुरोध बॉडी है, और secret Webhook सीक्रेट है। सत्यापन पूरा करने के लिए बस जनरेट किए गए सिग्नेचर (sha256= प्रीफ़िक्स सहित) की तुलना X-Webhook-Signature हेडर के मान से करें।

टाइमस्टैम्प वाला सिग्नेचर (X-Webhook-Signature-V2)

हर अनुरोध में X-Webhook-Signature-V2 भी होता है: v1= के बाद उसी Webhook सीक्रेट से {timestamp}.{body} का hex-एन्कोडेड HMAC-SHA256 — यानी X-Webhook-Timestamp हेडर का मान, एक बिंदु, और रॉ अनुरोध बॉडी।

Webhook सीक्रेट रोटेट करने के बाद, पुराना सीक्रेट 24 घंटे तक मान्य रहता है। इस अवधि में X-Webhook-Signature अब भी पुराने सीक्रेट से साइन होता है, और X-Webhook-Signature-V2 में हर सीक्रेट का एक मान होता है, कॉमा से अलग (v1=<old>,v1=<new>): अगर कोई भी मान मेल खाता है, तो अनुरोध स्वीकार करें।