Webhook-Benachrichtigungen

Empfangen Sie per Webhook die Ergebnisse von QR-Code-Zustellungen und Verlängerungen in Ihrer Anwendung.

Was ist ein Webhook?

iRoamly sendet Webhook-Benachrichtigungen zu QR-Code-Zustellungen und Verlängerungsergebnissen. Jeder Webhook verwendet HTTPS und enthält eine JSON-Payload. Mit Webhooks können Sie:

• QR-Code-Informationen empfangen, nachdem ein Einlösecode umgewandelt oder ein direkter QR-Code-Kauf abgeschlossen wurde.
• Verlängerungsergebnisse per Webhook empfangen: esim.renewal.success, wenn der QR-Code der Verlängerung bereit ist, esim.renewal.failed, wenn die vorgelagerte Verlängerungsbestellung fehlschlägt.

Antwortet Ihr Endpunkt nicht mit einem 2xx-Status, unternimmt iRoamly insgesamt bis zu 5 Zustellversuche: den ersten sofort, dann Wiederholungen nach 30 Sekunden, 2 Minuten, 3 Minuten und 5 Minuten.

Schritte zum Empfang eines Webhooks

Mit diesen Schritten empfangen Sie Ereignisse in Echtzeit in Ihrer App:

• Lokalen Endpunkt zum Empfang von Anfragen erstellen
• Registrieren Sie Ihren Webhook-Endpunkt im iRoamly Shop Dashboard unter Entwickler > Webhook-Benachrichtigungen

1. Lokalen Endpunkt zum Empfang von Anfragen erstellen

Erstellen Sie in Ihrer lokalen Anwendung eine neue Route, die POST-Anfragen annimmt.

Sie können zum Beispiel eine API-Route in Next.js hinzufügen:

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

Antworten Sie beim Empfang eines Ereignisses mit HTTP 200 OK, um iRoamly zu signalisieren, dass das Ereignis erfolgreich zugestellt wurde.

2. Ihren Entwicklungs-Webhook-Endpunkt registrieren

Registrieren Sie Ihre öffentlich erreichbare HTTPS-URL im iRoamly Shop Dashboard.

Mit einem Tool wie ngrok können Sie einen Tunnel zu Ihrem localhost-Server erstellen.

3. Testen, ob Ihr Webhook-Endpunkt richtig funktioniert

Wandeln Sie einen Test-Einlösecode in einen QR-Code um oder tätigen Sie einen direkten QR-Code-Kauf, um zu prüfen, ob Ihr Webhook-Endpunkt das Ereignis empfängt.

Liste der unterstützten Ereignistypen und ihrer Payloads.

Zustellung

Jedes Ereignis wird auf die gleiche Weise zugestellt: als POST-Anfrage mit JSON-Body an jeden Endpunkt, der das Ereignis abonniert hat. Jede 2xx-Antwort gilt als zugestellt; andernfalls wird erneut zugestellt, mit insgesamt bis zu 5 Versuchen (der erste sofort, dann Wiederholungen nach 30 Sekunden, 2 Minuten, 3 Minuten und 5 Minuten). Jede Anfrage enthält diese Header:

Unter „Webhook-Anfragen prüfen“ erfahren Sie, wie Sie die Signaturen prüfen.

esim.qrcode

Informationen zum eSIM-QR-Code, die nach dem Einlösen oder Kaufen des eSIM-QR-Codes zurückgegeben werden.

Beispiel-Anfragetext

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

Wird gesendet, wenn eine Verlängerung erfolgreich ist: Sobald der vorgelagerte Anbieter die Download-Daten der Verlängerungsbestellung liefert, erzeugt das System den QR-Code für den Verlängerungscode, und sein status wechselt zu 2 (Eingelöst).

Anfrage-Header

Die Anfrage enthält außerdem X-Webhook-Delivery, X-Webhook-Timestamp, X-Webhook-Signature und X-Webhook-Signature-V2, wie bei jedem Ereignis (siehe Ereignistypen).

Beispiel-Anfragetext

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

Felder

Wird gesendet, wenn eine Verlängerung fehlschlägt: Der vorgelagerte Anbieter beantwortet die Verlängerungsbestellung mit einem anderen Code als 0000, oder die Anfrage an den Anbieter schlägt fehl.

(Hinweis: Ein fehlender oder verspäteter Callback des vorgelagerten Anbieters löst dieses Ereignis nicht aus. Legen Sie ein Timeout fest und fragen Sie den Code ersatzweise ab – siehe „Umgang mit Verlängerungsereignissen“.)

Anfrage-Header

Die Anfrage enthält außerdem X-Webhook-Delivery, X-Webhook-Timestamp, X-Webhook-Signature und X-Webhook-Signature-V2, wie bei jedem Ereignis (siehe Ereignistypen).

Beispiel-Anfragetext

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

Felder

Verlängerungen werden nicht mehr als esim.qrcode zugestellt; dieses Ereignis wird für QR-Code-Umwandlungen und direkte QR-Code-Käufe gesendet. Im Vergleich zur Payload von esim.qrcode:

• event_type und der Header X-Webhook-Event sind esim.renewal.success oder esim.renewal.failed, und isrenew ist 1.
• data.code ist der durch die Verlängerung erzeugte neue Einlösecode; der verlängerte Code ist data.renewal_father_code.
• esim.renewal.success ergänzt renew_order_id, renewal_father_code, iscouldrenewal, download_url und iccid und hat keine order_id.
• Eine fehlgeschlagene Verlängerung wird durch esim.renewal.failed gemeldet, mit code -1 auf oberster Ebene und dem vorgelagerten Fehler in data.error_msg.

Neue Endpunkte abonnieren standardmäßig alle drei Ereignisse. Bestehende Endpunkte erhalten esim.renewal.success und esim.renewal.failed automatisch – es ist keine Änderung nötig.

• Gestalten Sie Ihren Handler idempotent. Durch eine Wiederholung kann dasselbe Ereignis mehrfach zugestellt werden. Deduplizieren Sie daher anhand von X-Webhook-Delivery oder von event_type + data.code und ignorieren Sie bereits verarbeitete Ereignisse.
• Verwenden Sie ein Timeout als Rückfallebene. Trifft innerhalb einer angemessenen Zeit weder esim.renewal.success noch esim.renewal.failed ein, fragen Sie den Code über die Abfrage-API ab (zum Beispiel „QR-Code abfragen“), statt von einer fehlgeschlagenen Verlängerung auszugehen.
• Entscheiden Sie Rückerstattungen nicht anhand von esim.renewal.failed. Das Ereignis meldet nur, dass die vorgelagerte Bestellung fehlgeschlagen ist; ob und wann die Credits erstattet werden, wird separat entschieden. Erstatten Sie Ihren Kunden daher nichts auf Grundlage dieses Ereignisses.

Prüfen Sie die iRoamly-Signatur von Webhook-Anfragen.

Wie prüfe ich die iRoamly-Signatur?

Die iRoamly-Signatur wird im Header X-Webhook-Signature der Webhook-Anfrage gesendet, als sha256= gefolgt von der hexadezimal codierten Signatur. Die Signatur wird mit dem HMAC-SHA256-Algorithmus erzeugt, mit dem Webhook-Secret als Schlüssel und dem unveränderten Anfragetext (genau wie empfangen, vor jedem JSON-Parsing) als Nachricht.

Beispiel-Webhook-Header

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

Ihr Webhook-Secret finden Sie im Dashboard unter Entwickler > Webhook-Benachrichtigungen.

Um die Signatur zu erzeugen, können Sie das folgende Code-Snippet verwenden:

import * as crypto from 'crypto';

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

Im obigen Code-Snippet ist payload der unveränderte Anfragetext und secret das Webhook-Secret. Vergleichen Sie einfach die erzeugte Signatur (einschließlich des Präfixes sha256=) mit dem Wert des Headers X-Webhook-Signature, um die Prüfung abzuschließen.

Signatur mit Zeitstempel (X-Webhook-Signature-V2)

Jede Anfrage enthält außerdem X-Webhook-Signature-V2: v1= gefolgt vom hexadezimal codierten HMAC-SHA256 mit demselben Webhook-Secret über {timestamp}.{body} – den Wert des Headers X-Webhook-Timestamp, einen Punkt und den unveränderten Anfragetext.

Nach der Rotation des Webhook-Secrets bleibt das alte Secret 24 Stunden lang gültig. In diesem Zeitraum wird X-Webhook-Signature weiterhin mit dem alten Secret signiert, und X-Webhook-Signature-V2 enthält einen Wert pro Secret, durch Kommas getrennt (v1=<old>,v1=<new>): Akzeptieren Sie die Anfrage, wenn einer der Werte übereinstimmt.