Webhooks
Instead of polling for the OTP, you can have the Supersim API push updates to your endpoint the moment they happen.
1. Set your webhook URL
Section titled “1. Set your webhook URL”import requests
resp = requests.put( "https://su-persim.uz/api/v1/user/webhook", headers={ "X-API-Key": "supersim_YOUR_API_KEY", "Content-Type": "application/json", }, json={"url": "https://your-server.example/hook"},)print(resp.json())<?php
$ch = curl_init("https://su-persim.uz/api/v1/user/webhook");curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "PUT");curl_setopt($ch, CURLOPT_HTTPHEADER, [ "X-API-Key: supersim_YOUR_API_KEY", "Content-Type: application/json",]);curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([ "url" => "https://your-server.example/hook",]));echo curl_exec($ch);curl_close($ch);const res = await fetch("https://su-persim.uz/api/v1/user/webhook", {method: "PUT",headers: { "Content-Type": "application/json", "X-API-Key": "supersim_YOUR_API_KEY",},body: JSON.stringify({ url: "https://your-server.example/hook" }),});console.log(await res.json());To stop receiving events, send {"url": null}.
2. Payload format
Section titled “2. Payload format”We send an HTTP POST with the Content-Type: application/json header to your URL whenever an order is updated:
{ "event": "order.update", "order": { "order_id": 42, "phone_number": "+393791700000", "country_name": "Italy", "account_type": "ready", "status": "otp_ready", "otp_code": "12345", "price": 1.5 }, "sent_at": "2026-08-15T18:05:00"}| Field | Description |
|---|---|
event |
Always "order.update". |
order.order_id |
The order that changed. |
order.status |
paid → otp_ready → completed. |
order.otp_code |
The login code (only present when status is otp_ready). |
sent_at |
When the event was dispatched. |
3. Receiving webhooks
Section titled “3. Receiving webhooks”from fastapi import FastAPI, Request
app = FastAPI()
@app.post("/hook")async def hook(request: Request): payload = await request.json() if payload["event"] == "order.update": order = payload["order"] print( f"Order {order['order_id']} is now {order['status']}" f" — code: {order.get('otp_code')}" ) return {"status": "ok"}<?php
// Your webhook endpoint (e.g. /hook.php)$payload = json_decode(file_get_contents("php://input"), true);
if ($payload["event"] === "order.update") { $order = $payload["order"]; echo "Order {$order['order_id']} is now {$order['status']}" . " — code: " . ($order["otp_code"] ?? "n/a") . PHP_EOL;}
http_response_code(200);echo json_encode(["status" => "ok"]);// Express.js webhook endpointimport express from "express";const app = express();app.use(express.json());
app.post("/hook", (req, res) => {const payload = req.body;if (payload.event === "order.update") { const order = payload.order; console.log( `Order ${order.order_id} is now ${order.status} — code: ${order.otp_code ?? "n/a"}` );}res.json({ status: "ok" });});Security
Section titled “Security”Your endpoint receives no API key, so anyone who knows your webhook URL can receive your OTP codes. Use an HTTPS URL and treat the URL itself as a secret.