Notifiche Webhook

Usa i webhook per ricevere nella tua applicazione i risultati di consegna dei codici QR e dei rinnovi.

Che cos’è un webhook?

iRoamly invia notifiche webhook per la consegna dei codici QR e i risultati dei rinnovi. Ogni webhook usa HTTPS e include un payload JSON. Con i webhook puoi:

• Ricevere le informazioni del codice QR dopo la conversione di un codice di riscatto o il completamento di un acquisto diretto di codice QR.
• Ricevere l’esito dei rinnovi tramite webhook: esim.renewal.success quando il codice QR del rinnovo è pronto, esim.renewal.failed quando l’ordine di rinnovo presso il fornitore non riesce.

Se il tuo endpoint non risponde con uno stato 2xx, iRoamly effettua fino a 5 tentativi di consegna in totale: il primo subito, poi nuovi tentativi dopo 30 secondi, 2 minuti, 3 minuti e 5 minuti.

Passaggi per ricevere un webhook

Puoi iniziare a ricevere eventi in tempo reale nella tua app con questi passaggi:

• Crea un endpoint locale per ricevere le richieste
• Registra il tuo endpoint webhook in Sviluppatori > Notifiche Webhook nella Dashboard di iRoamly Shop

1. Crea un endpoint locale per ricevere le richieste

Nella tua applicazione locale, crea una nuova route in grado di accettare richieste POST.

Ad esempio, puoi aggiungere una route API in 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);
  }
};

Alla ricezione di un evento, rispondi con HTTP 200 OK per segnalare a iRoamly che l’evento è stato consegnato correttamente.

2. Registra il tuo endpoint webhook di sviluppo

Registra il tuo URL HTTPS accessibile pubblicamente nella Dashboard di iRoamly Shop.

Puoi creare un tunnel verso il tuo server localhost con uno strumento come ngrok.

3. Verifica che l’endpoint webhook funzioni correttamente

Converti un codice di riscatto di prova in codice QR, oppure effettua un acquisto diretto di codice QR, per verificare che il tuo endpoint webhook riceva l’evento.

Elenco dei tipi di evento supportati e dei relativi payload.

Consegna

Ogni evento viene consegnato allo stesso modo: una richiesta POST con corpo JSON a ciascun endpoint iscritto all’evento. Qualsiasi risposta 2xx vale come consegna; altrimenti la richiesta viene ritentata, fino a 5 tentativi in totale (il primo subito, poi nuovi tentativi dopo 30 secondi, 2 minuti, 3 minuti e 5 minuti). Ogni richiesta contiene questi header:

Vedi Verifica delle richieste webhook per sapere come controllare le firme.

esim.qrcode

Informazioni sul codice QR dell’eSIM restituite dopo il riscatto o l’acquisto del codice QR dell’eSIM.

Corpo della richiesta di esempio

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

Inviato quando un rinnovo riesce: quando il fornitore restituisce i dati di download dell’ordine di rinnovo, il sistema genera il codice QR del codice di rinnovo e il suo status diventa 2 (Riscattato).

Header della richiesta

La richiesta contiene anche X-Webhook-Delivery, X-Webhook-Timestamp, X-Webhook-Signature e X-Webhook-Signature-V2, come ogni evento (vedi Tipi di evento).

Corpo della richiesta di esempio

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

Campi

Inviato quando un rinnovo non riesce: il fornitore risponde all’ordine di rinnovo con un codice diverso da 0000, oppure la richiesta al fornitore non riesce.

(Nota: un callback del fornitore mancante o in ritardo non attiva questo evento. Imposta un timeout e ripiega sull’interrogazione del codice: vedi Gestione degli eventi di rinnovo.)

Header della richiesta

La richiesta contiene anche X-Webhook-Delivery, X-Webhook-Timestamp, X-Webhook-Signature e X-Webhook-Signature-V2, come ogni evento (vedi Tipi di evento).

Corpo della richiesta di esempio

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

Campi

I rinnovi non vengono più consegnati come esim.qrcode; questo evento viene inviato per le conversioni in codice QR e gli acquisti diretti di codici QR. Rispetto al payload di esim.qrcode:

• event_type e l’header X-Webhook-Event valgono esim.renewal.success o esim.renewal.failed, e isrenew vale 1.
• data.code è il nuovo codice di riscatto creato dal rinnovo; il codice rinnovato è data.renewal_father_code.
• esim.renewal.success aggiunge renew_order_id, renewal_father_code, iscouldrenewal, download_url e iccid, e non contiene order_id.
• Un rinnovo non riuscito viene segnalato da esim.renewal.failed, con code di primo livello -1 e l’errore del fornitore in data.error_msg.

I nuovi endpoint sono iscritti per impostazione predefinita a tutti e tre gli eventi. Gli endpoint esistenti ricevono automaticamente esim.renewal.success ed esim.renewal.failed: non serve alcuna modifica.

• Rendi idempotente il tuo gestore. Un nuovo tentativo può consegnare lo stesso evento più di una volta, quindi deduplica in base a X-Webhook-Delivery o a event_type + data.code e ignora gli eventi già elaborati.
• Prevedi un timeout di riserva. Se né esim.renewal.success né esim.renewal.failed arrivano entro un tempo ragionevole, interroga il codice con l’API di interrogazione (ad esempio Query QR Code) invece di presumere che il rinnovo non sia riuscito.
• Non usare esim.renewal.failed per decidere i rimborsi. Segnala solo che l’ordine presso il fornitore non è riuscito; se e quando i crediti vengono restituiti è deciso separatamente, quindi non rimborsare i tuoi clienti in base a questo evento.

Verifica la firma di iRoamly sulle richieste webhook.

Come verificare la firma di iRoamly?

La firma di iRoamly viene inviata nell’header X-Webhook-Signature della richiesta webhook, come sha256= seguito dalla firma codificata in esadecimale. La firma è generata con l’algoritmo HMAC-SHA256, usando il segreto del webhook come chiave e il corpo grezzo della richiesta (esattamente come ricevuto, prima di qualsiasi parsing JSON) come messaggio.

Header webhook di esempio

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

Trovi il segreto del webhook in Sviluppatori > Notifiche Webhook nella Dashboard.

Per generare la firma, puoi usare il seguente frammento di codice:

import * as crypto from 'crypto';

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

Nel frammento di codice qui sopra, payload è il corpo grezzo della richiesta e secret è il segreto del webhook. Confronta semplicemente la firma generata (incluso il prefisso sha256=) con il valore dell’header X-Webhook-Signature per completare la verifica.

Firma con timestamp (X-Webhook-Signature-V2)

Ogni richiesta contiene anche X-Webhook-Signature-V2: v1= seguito dall’HMAC-SHA256 codificato in esadecimale, con lo stesso segreto del webhook, di {timestamp}.{body}, ovvero il valore dell’header X-Webhook-Timestamp, un punto e il corpo grezzo della richiesta.

Dopo la rotazione del segreto del webhook, il vecchio segreto resta valido per 24 ore. In quel periodo X-Webhook-Signature è ancora firmato con il vecchio segreto e X-Webhook-Signature-V2 contiene un valore per ogni segreto, separati da virgole (v1=<old>,v1=<new>): accetta la richiesta se uno qualsiasi dei valori corrisponde.