Webhooks

Receive real-time notifications for order status changes and profile events.

Set Webhook URL

Endpoint: POST /api/v1/open/webhook/save

Request Parameters

Name	Type	Required	Description
`webhook`	String	Required	Your webhook endpoint URL

Example Request

curl --location --request POST 'https://your-api-domain.com/api/v1/open/webhook/save' \
--header 'RT-AccessCode: YOUR_ACCESS_CODE' \
--header 'RT-SecretKey: YOUR_SECRET_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "webhook": "https://your-server.com/api/webhooks/esim"
}'

Example Success Response

{
    "errorCode": null,
    "errorMsg": null,
    "success": true,
    "obj": null
}

Webhook Events

Your webhook endpoint will receive POST requests with various event types for order status changes, profile status updates, and data usage alerts.

Order Status Events

{
    "eventType": "ORDER_STATUS",
    "orderNo": "ORD20240101123456",
    "transactionId": "order_123456",
    "status": "GOT_RESOURCE",
    "timestamp": "2024-01-15T12:30:45Z",
    "profiles": [
        {
            "iccid": "8901234567890123456",
            "esimTranNo": "ESIM123456",
            "status": "GOT_RESOURCE"
        }
    ]
}

Profile Status Events

{
    "eventType": "PROFILE_STATUS",
    "iccid": "8901234567890123456",
    "orderNo": "ORD20240101123456",
    "previousStatus": "GOT_RESOURCE",
    "currentStatus": "ACTIVATED",
    "timestamp": "2024-01-15T14:00:00Z"
}

Data Usage Events

{
    "eventType": "DATA_USAGE",
    "iccid": "8901234567890123456",
    "usedVolume": 859832320,
    "totalVolume": 1073741824,
    "usagePercent": 80,
    "timestamp": "2024-01-16T08:00:00Z"
}

Event Types Summary

Event Type	Description
`ORDER_STATUS`	Order created or status changed
`PROFILE_STATUS`	Profile status changed (activated, suspended, etc.)
`DATA_USAGE`	Data usage threshold reached (50%, 80%, 100%)

Implementing Your Webhook

Example Node.js/Express Handler

const express = require('express');
const app = express();
 
app.post('/api/webhooks/esim', express.json(), (req, res) => {
    const event = req.body;
 
    console.log('Received webhook:', event.eventType);
 
    switch (event.eventType) {
        case 'ORDER_STATUS':
            handleOrderStatus(event);
            break;
        case 'PROFILE_STATUS':
            handleProfileStatus(event);
            break;
        case 'DATA_USAGE':
            handleDataUsage(event);
            break;
        default:
            console.log('Unknown event type:', event.eventType);
    }
 
    // Always respond with 200 to acknowledge receipt
    res.status(200).json({ received: true });
});
 
function handleOrderStatus(event) {
    // Update order status in your database
    console.log(`Order ${event.orderNo} status: ${event.status}`);
}
 
function handleProfileStatus(event) {
    // Notify customer of profile activation
    if (event.currentStatus === 'ACTIVATED') {
        // Send activation confirmation email
    }
}
 
function handleDataUsage(event) {
    // Warn customer of low data
    if (event.usagePercent >= 80) {
        // Send low data warning
    }
}

Example Next.js API Route

// app/api/webhooks/esim/route.ts
import { NextRequest, NextResponse } from 'next/server';
 
export async function POST(request: NextRequest) {
    const event = await request.json();
 
    console.log('Webhook received:', event.eventType);
 
    switch (event.eventType) {
        case 'ORDER_STATUS':
            await handleOrderStatus(event);
            break;
        case 'PROFILE_STATUS':
            await handleProfileStatus(event);
            break;
        case 'DATA_USAGE':
            await handleDataUsage(event);
            break;
    }
 
    return NextResponse.json({ received: true });
}
 
async function handleOrderStatus(event: any) {
    // Update order in database
}
 
async function handleProfileStatus(event: any) {
    // Handle profile status change
}
 
async function handleDataUsage(event: any) {
    // Handle data usage alert
}

Best Practices

Respond quickly - Return 200 status within 5 seconds
Process asynchronously - Queue webhook data for background processing
Handle duplicates - Webhooks may be sent multiple times
Verify source - Validate the webhook is from the platform
Log all events - Keep records for debugging and auditing

Testing Webhooks

Use services like webhook.site or ngrok to test webhooks during development:

# Using ngrok to expose local server
ngrok http 3000
 
# Then set your webhook URL
curl --location --request POST 'https://your-api-domain.com/api/v1/open/webhook/save' \
--header 'RT-AccessCode: YOUR_ACCESS_CODE' \
--header 'RT-SecretKey: YOUR_SECRET_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "webhook": "https://abc123.ngrok.io/api/webhooks/esim"
}'

Top Up Send SMS