Webhook bildirimleri

QR kod teslimatı ve yenileme sonuçlarını uygulamanızda almak için webhook’ları kullanın.

Webhook nedir?

iRoamly, QR kod teslimatı ve yenileme sonuçları için webhook bildirimleri gönderir. Her webhook HTTPS kullanır ve bir JSON yükü içerir. Webhook’larla şunları yapabilirsiniz:

• Bir kullanım kodu dönüştürüldükten veya doğrudan QR kod satın alımı tamamlandıktan sonra QR kod bilgilerini alın.
• Yenileme sonuçlarını webhook ile alın: yenileme QR kodu hazır olduğunda esim.renewal.success, üst sağlayıcıdaki yenileme siparişi başarısız olduğunda esim.renewal.failed.

Uç noktanız 2xx durum koduyla yanıt vermezse iRoamly toplamda en fazla 5 teslimat denemesi yapar: ilki hemen, ardından 30 saniye, 2 dakika, 3 dakika ve 5 dakika sonra yeniden dener.

Webhook alma adımları

Şu adımlarla uygulamanızda gerçek zamanlı olayları almaya başlayabilirsiniz:

• İstekleri almak için yerel bir uç nokta oluşturun
• Webhook uç noktanızı iRoamly Shop panelinde Geliştiriciler > Webhook bildirimleri altında kaydedin

1. İstekleri almak için yerel bir uç nokta oluşturun

Yerel uygulamanızda POST isteklerini kabul edebilen yeni bir rota oluşturun.

Örneğin Next.js’te bir API rotası ekleyebilirsiniz:

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);
  }
};

Bir olay aldığınızda, olayın başarıyla teslim edildiğini iRoamly’ye bildirmek için HTTP 200 OK ile yanıt vermelisiniz.

2. Geliştirme webhook uç noktanızı kaydedin

Herkese açık HTTPS URL’nizi iRoamly Shop panelinde kaydedin.

ngrok gibi bir araçla localhost sunucunuza bir tünel oluşturabilirsiniz.

3. Webhook uç noktanızın düzgün çalıştığını test edin

Webhook uç noktanızın olayı aldığını kontrol etmek için bir test kullanım kodunu QR koda dönüştürün veya doğrudan bir QR kod satın alımı yapın.

Desteklenen olay türlerinin ve yüklerinin listesi.

Teslimat

Her olay aynı şekilde teslim edilir: olaya abone olan her uç noktaya JSON gövdeli bir POST isteği. Herhangi bir 2xx yanıt teslim edildi sayılır; aksi halde istek yeniden denenir, toplamda en fazla 5 deneme yapılır (ilki hemen, ardından 30 saniye, 2 dakika, 3 dakika ve 5 dakika sonra). Her istek şu header’ları taşır:

İmzaların nasıl kontrol edileceği için Webhook isteklerini doğrulama bölümüne bakın.

esim.qrcode

eSIM QR kodu kullanıldıktan veya satın alındıktan sonra döndürülen eSIM QR koduyla ilgili bilgiler.

Örnek istek gövdesi

{
	"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"
	}

Bir yenileme başarılı olduğunda gönderilir: üst sağlayıcı yenileme siparişinin indirme bilgilerini döndürdüğünde sistem yenileme kodu için QR kodu oluşturur ve kodun status değeri 2 (Kullanıldı) olur.

İstek header’ları

İstek, her olayda olduğu gibi X-Webhook-Delivery, X-Webhook-Timestamp, X-Webhook-Signature ve X-Webhook-Signature-V2 header’larını da taşır (bkz. Olay türleri).

Örnek istek gövdesi

{
	"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"
}

Alanlar

Bir yenileme başarısız olduğunda gönderilir: üst sağlayıcı yenileme siparişine 0000 dışında bir kodla yanıt verir veya sağlayıcıya yapılan istek başarısız olur.

(Not: Üst sağlayıcıdan gelmeyen veya geciken bir geri çağrı bu olayı tetiklemez. Bir zaman aşımı belirleyin ve kodu sorgulamaya geri dönün — bkz. Yenileme olaylarını işleme.)

İstek header’ları

İstek, her olayda olduğu gibi X-Webhook-Delivery, X-Webhook-Timestamp, X-Webhook-Signature ve X-Webhook-Signature-V2 header’larını da taşır (bkz. Olay türleri).

Örnek istek gövdesi

{
	"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"
}

Alanlar

Yenilemeler artık esim.qrcode olarak teslim edilmez; bu olay QR kod dönüştürmeleri ve doğrudan QR kod satın alımları için gönderilir. esim.qrcode yüküyle karşılaştırıldığında:

• event_type ve X-Webhook-Event header’ı esim.renewal.success veya esim.renewal.failed olur ve isrenew değeri 1 olur.
• data.code, yenilemeyle oluşturulan yeni kullanım kodudur; yenilenen kod ise data.renewal_father_code alanındadır.
• esim.renewal.success; renew_order_id, renewal_father_code, iscouldrenewal, download_url ve iccid alanlarını ekler ve order_id içermez.
• Başarısız bir yenileme, üst düzey code değeri -1 ve data.error_msg içindeki üst sağlayıcı hatasıyla esim.renewal.failed tarafından bildirilir.

Yeni uç noktalar varsayılan olarak üç olayın tümüne abone olur. Mevcut uç noktalar esim.renewal.success ve esim.renewal.failed olaylarını otomatik olarak alır — herhangi bir değişiklik gerekmez.

• İşleyicinizi idempotent yapın. Bir yeniden deneme aynı olayı birden fazla kez teslim edebilir; bu nedenle X-Webhook-Delivery veya event_type + data.code ile tekilleştirin ve daha önce işlediğiniz olayları yok sayın.
• Zaman aşımı yedeği kullanın. Makul bir süre içinde ne esim.renewal.success ne de esim.renewal.failed gelirse, yenilemenin başarısız olduğunu varsaymak yerine kodu sorgu API’siyle (örneğin QR Kod Sorgula) sorgulayın.
• İade kararları için esim.renewal.failed olayını kullanmayın. Bu olay yalnızca üst sağlayıcı siparişinin başarısız olduğunu bildirir; kredinin iade edilip edilmeyeceğine ve ne zaman edileceğine ayrıca karar verilir, bu nedenle müşterilerinize bu olaya dayanarak iade yapmayın.

Webhook isteklerindeki iRoamly imzasını doğrulayın.

iRoamly imzası nasıl doğrulanır?

iRoamly imzası, webhook isteğinin X-Webhook-Signature header’ında sha256= ve ardından onaltılık kodlu imza olarak gönderilir. İmza, anahtar olarak webhook gizli anahtarı ve mesaj olarak ham istek gövdesi (alındığı haliyle, herhangi bir JSON ayrıştırmasından önce) kullanılarak HMAC-SHA256 algoritmasıyla oluşturulur.

Örnek webhook header’ı

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

Webhook gizli anahtarınızı panelde Geliştiriciler > Webhook bildirimleri altında bulabilirsiniz.

İmzayı oluşturmak için aşağıdaki kod parçacığını kullanabilirsiniz:

import * as crypto from 'crypto';

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

Yukarıdaki kod parçacığında payload ham istek gövdesi, secret ise webhook gizli anahtarıdır. Doğrulamayı tamamlamak için oluşturulan imzayı (sha256= öneki dahil) X-Webhook-Signature header değeriyle karşılaştırmanız yeterlidir.

Zaman damgalı imza (X-Webhook-Signature-V2)

Her istek ayrıca X-Webhook-Signature-V2 header’ını taşır: v1= ve ardından aynı webhook gizli anahtarıyla {timestamp}.{body} değerinin onaltılık kodlu HMAC-SHA256 değeri — yani X-Webhook-Timestamp header değeri, bir nokta ve ham istek gövdesi.

Webhook gizli anahtarını değiştirdikten sonra eski anahtar 24 saat geçerli kalır. Bu süre boyunca X-Webhook-Signature hâlâ eski anahtarla imzalanır ve X-Webhook-Signature-V2 her anahtar için virgülle ayrılmış birer değer taşır (v1=<old>,v1=<new>): değerlerden herhangi biri eşleşirse isteği kabul edin.