Notifications Webhook

Utilisez les webhooks pour recevoir dans votre application les résultats de livraison des QR codes et de renouvellement.

Qu’est-ce qu’un webhook ?

iRoamly envoie des notifications webhook pour la livraison des QR codes et les résultats de renouvellement. Chaque webhook utilise HTTPS et inclut un contenu JSON. Les webhooks vous permettent de :

• Recevoir les informations du QR code après la conversion d’un code d’échange ou la finalisation d’un achat direct de QR code.
• Recevoir les résultats des renouvellements par webhook : esim.renewal.success lorsque le QR code de renouvellement est prêt, esim.renewal.failed lorsque la commande de renouvellement auprès du fournisseur échoue.

Si votre point de terminaison ne répond pas avec un statut 2xx, iRoamly effectue jusqu’à 5 tentatives de livraison au total : la première immédiatement, puis de nouvelles tentatives après 30 secondes, 2 minutes, 3 minutes et 5 minutes.

Étapes pour recevoir un webhook

Vous pouvez commencer à recevoir des événements en temps réel dans votre application en suivant ces étapes :

• Créer un point de terminaison local pour recevoir les requêtes
• Enregistrer votre point de terminaison webhook dans Développeurs > Notifications Webhook du tableau de bord iRoamly Shop

1. Créer un point de terminaison local pour recevoir les requêtes

Dans votre application locale, créez une nouvelle route acceptant les requêtes POST.

Par exemple, vous pouvez ajouter une route API dans Next.js :

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

À la réception d’un événement, répondez avec HTTP 200 OK pour indiquer à iRoamly que l’événement a bien été livré.

2. Enregistrer votre point de terminaison webhook de développement

Enregistrez votre URL HTTPS accessible publiquement dans le tableau de bord iRoamly Shop.

Vous pouvez créer un tunnel vers votre serveur localhost avec un outil comme ngrok.

3. Vérifier que votre point de terminaison webhook fonctionne correctement

Convertissez un code d’échange de test en QR code, ou effectuez un achat direct de QR code, pour vérifier que votre point de terminaison webhook reçoit l’événement.

Liste des types d’événements pris en charge et de leur contenu.

Livraison

Tous les événements sont livrés de la même façon : une requête POST avec un corps JSON, envoyée à chaque point de terminaison abonné à l’événement. Toute réponse 2xx vaut livraison ; sinon, la requête est renvoyée, jusqu’à 5 tentatives au total (la première immédiatement, puis de nouvelles tentatives après 30 secondes, 2 minutes, 3 minutes et 5 minutes). Chaque requête contient ces en-têtes :

Consultez « Vérifier les requêtes webhook » pour savoir comment contrôler les signatures.

esim.qrcode

Informations relatives au QR code eSIM renvoyées après l’échange ou l’achat du QR code eSIM.

Exemple de corps de requête

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

Envoyé lorsqu’un renouvellement réussit : dès que le fournisseur renvoie les informations de téléchargement de la commande de renouvellement, le système génère le QR code du code de renouvellement et son status passe à 2 (Échangé).

En-têtes de la requête

La requête contient aussi X-Webhook-Delivery, X-Webhook-Timestamp, X-Webhook-Signature et X-Webhook-Signature-V2, comme pour tous les événements (voir « Types d’événements »).

Exemple de corps de requête

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

Champs

Envoyé lorsqu’un renouvellement échoue : le fournisseur répond à la commande de renouvellement avec un code autre que 0000, ou la requête vers le fournisseur échoue.

(Remarque : un rappel du fournisseur absent ou tardif ne déclenche pas cet événement. Définissez un délai d’expiration et consultez le code en solution de repli — voir « Gestion des événements de renouvellement ».)

En-têtes de la requête

La requête contient aussi X-Webhook-Delivery, X-Webhook-Timestamp, X-Webhook-Signature et X-Webhook-Signature-V2, comme pour tous les événements (voir « Types d’événements »).

Exemple de corps de requête

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

Champs

Les renouvellements ne sont plus livrés via esim.qrcode ; cet événement est envoyé pour les conversions en QR code et les achats directs de QR codes. Par rapport au contenu de esim.qrcode :

• event_type et l’en-tête X-Webhook-Event valent esim.renewal.success ou esim.renewal.failed, et isrenew vaut 1.
• data.code est le nouveau code d’échange créé par le renouvellement ; le code renouvelé est data.renewal_father_code.
• esim.renewal.success ajoute renew_order_id, renewal_father_code, iscouldrenewal, download_url et iccid, et n’a pas de order_id.
• Un renouvellement échoué est signalé par esim.renewal.failed, avec un code de premier niveau égal à -1 et l’erreur du fournisseur dans data.error_msg.

Les nouveaux points de terminaison sont abonnés par défaut aux trois événements. Les points de terminaison existants reçoivent automatiquement esim.renewal.success et esim.renewal.failed — aucune modification n’est nécessaire.

• Rendez votre gestionnaire idempotent. Une nouvelle tentative peut livrer le même événement plusieurs fois : dédoublonnez par X-Webhook-Delivery ou par event_type + data.code, et ignorez les événements déjà traités.
• Prévoyez un repli après délai. Si ni esim.renewal.success ni esim.renewal.failed n’arrive dans un délai raisonnable, consultez le code avec l’API de consultation (par exemple « Consulter le QR code ») au lieu de supposer que le renouvellement a échoué.
• N’utilisez pas esim.renewal.failed pour décider des remboursements. Il signale uniquement l’échec de la commande auprès du fournisseur ; la restitution éventuelle des crédits et sa date sont décidées séparément, ne remboursez donc pas vos clients sur la base de cet événement.

Vérifiez la signature iRoamly des requêtes webhook.

Comment vérifier la signature iRoamly ?

La signature iRoamly est envoyée dans l’en-tête X-Webhook-Signature de la requête webhook, sous la forme sha256= suivi de la signature encodée en hexadécimal. La signature est générée avec l’algorithme HMAC-SHA256, avec le secret du webhook comme clé et le corps brut de la requête (tel que reçu, avant toute analyse JSON) comme message.

Exemple d’en-tête webhook

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

Votre secret de webhook se trouve dans Développeurs > Notifications Webhook du tableau de bord.

Pour générer la signature, vous pouvez utiliser l’extrait de code suivant :

import * as crypto from 'crypto';

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

Dans l’extrait ci-dessus, payload est le corps brut de la requête et secret le secret du webhook. Il suffit de comparer la signature générée (préfixe sha256= compris) avec la valeur de l’en-tête X-Webhook-Signature pour terminer la vérification.

Signature horodatée (X-Webhook-Signature-V2)

Chaque requête contient aussi X-Webhook-Signature-V2 : v1= suivi du HMAC-SHA256 encodé en hexadécimal, avec le même secret de webhook, de {timestamp}.{body} — la valeur de l’en-tête X-Webhook-Timestamp, un point, puis le corps brut de la requête.

Après une rotation du secret de webhook, l’ancien secret reste valide pendant 24 heures. Pendant cette période, X-Webhook-Signature est toujours signé avec l’ancien secret, et X-Webhook-Signature-V2 contient une valeur par secret, séparées par des virgules (v1=<old>,v1=<new>) : acceptez la requête si l’une des valeurs correspond.