Skip to content

Webhooks

Instead of polling for the OTP, you can have the Supersim API push updates to your endpoint the moment they happen.

PUT /api/v1/user/webhook
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())

To stop receiving events, send {"url": null}.

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.
Your endpoint — receiving order.update
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"}

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.