Overview
How webhooks send events to your endpoint, what each request contains, and what to do when a request fails.
For postpaid SIM service only
The webhook APIs return 403 if your partner account does not have postpaid SIM service.
A webhook sends events from Peplink to your HTTPS endpoint when the events occur. Your systems do not have to request the data again and again. Your partner account can have a maximum of 10 webhooks. Each webhook subscribes to one or more event types.
Required Capabilities
The webhook APIs need an API key with one of these capabilities. To create an API key, see API Keys.
| Capability | Permissions |
|---|---|
Webhook Viewer | View webhooks and their events. |
Webhook Manager | Create, update, delete and test webhooks. Redeliver events. |
Webhook Admin | All Webhook Manager permissions. Grant Webhook capabilities to members. |
Event Types
| Event type | Sent when |
|---|---|
POSTPAID_SIM_USAGE_UPDATED | The live usage of one or more postpaid SIMs in your partner account changes. |
Receiving Events
Peplink sends each event to the URL of the webhook as a POST request. The request has these headers:
| Header | Value |
|---|---|
Authorization | Bearer <token>. <token> is the token of the webhook. |
Content-Type | application/json |
User-Agent | Peplink-Webhook/1.0 |
Compare the Authorization header with your token. Reject the request if they are different. Peplink does not
sign the requests.
Request body
ID of the event. All attempts of an event have the same ID. Use it to ignore duplicates.
Type of the event.
POSTPAID_SIM_USAGE_UPDATED— The live usage of one or more postpaid SIMs in your partner account changes
Time of when the event is created.
Data of the event. Its structure depends on eventType.
true if the request is a test with sample data. Otherwise false.
POSTPAID_SIM_USAGE_UPDATED data
Live usage of each SIM and month that changed. One request can contain many SIMs. It contains only the postpaid SIMs in your partner account.
Show child attributes
ICCID of the sim.
Year of the month that the usage is for, in UTC.
Month that the usage is for, in UTC. The value is 1 to 12.
Usage from the start of the month, in MB, rounded to 2 decimal places.
Time of the latest usage report in usageMb. Use it to see how recent the usage is.
Live usage is an estimate for monitoring. It is not the billed usage. For the billed usage, use Search postpaid usages. A month is a calendar month in UTC.
Each item gives the usage from the start of the month. It does not give the usage since the last request. For each
iccid, year and month, keep the item with the latest lastEventAt. To check one SIM again, use
Get live usage of a SIM.
Example
{
"eventId": "66fd0c1e8a1b2c3d4e5f6a7b",
"eventType": "POSTPAID_SIM_USAGE_UPDATED",
"createdAt": "2026-10-02T01:20:00.000Z",
"data": {
"items": [
{
"iccid": "89000000000000000000",
"year": 2026,
"month": 10,
"usageMb": 886.94,
"lastEventAt": "2026-10-02T01:18:41.000Z"
},
{
"iccid": "89000000000000000001",
"year": 2026,
"month": 10,
"usageMb": 12.5,
"lastEventAt": "2026-10-02T01:19:03.000Z"
}
]
},
"test": false
}Responding to Events
Send a 2xx response in 10 seconds or less. These results are failed attempts: a status other than 2xx, a
redirect, or no response.
When an attempt fails, Peplink sends the event again, with a maximum of 3 attempts. After the third failed
attempt, the status of the event changes to FAILED, and Peplink stops. When your endpoint is available again,
find the event with search events and
redeliver it.
Each attempt sends the same body with the same eventId. Use eventId to ignore the events that you processed
before. Events can arrive in a different order.
Webhook URL
The URL must use https and a public internet address. Peplink refuses a URL on a private network, and a URL
that resolves to a private address. It checks the URL when you save the webhook and before each request.
Testing
To check your endpoint, send a test push. Peplink sends one event with sample
data, with test set to true. The response gives the request that Peplink sent and the response from your
endpoint.