Usage Alerts (POST Service)
Overview
SIM Insight can generate usage alerts when defined thresholds are reached.
Alerts are typically delivered by email. If required, alerts can also be delivered via HTTPS POST to your server.
POST requests are sent with:
- Content-Type: text/xml (UTF-8 encoded)
- User-Agent: CSL SIM Insight/1.0.0
- Payload: XML (formats shown below)
For initial testing, HTTP POST may also be enabled.
Endpoint Configuration
You may provide:
- A primary resource URL
- An optional backup resource URL
- An optional passphrase
Example endpoints:
- https://primeserver.clientdomain.com/AlertsHandler.aspx
- https://secondaryserver.clientdomain.uk/AlertsHandler2.aspx
Delivery Behaviour
When the service is enabled:
- Alerts are queued in the order generated
- Items are delivered on a first-in, first-out (FIFO) basis
- If delivery to the primary URL fails, the backup URL (if specified) is attempted
If both endpoints fail, retries occur on the following schedule:
5s → 10s → 30s → 1m → 2m → 5m → every 15 minutes thereafter
Undelivered alerts are held indefinitely.
It is possible for alerts to be delivered more than once if the HTTP response code does not reach the platform. Endpoints must safely handle duplicate events.
Alert Configuration
Each alert type can be configured on a group-by-group basis via the SIM Insight portal.
Delivery can be configured for:
- API POST
- Or both
Alert Payloads
Each alert type is delivered as a separate XML payload.
SIM Usage Warning Reached
<post-alert-sim-warning version="1" api-did="0000187011">
<passphrase>password</passphrase>
<iccid>1234567890123456789</iccid>
<warning-level-mb>2560</warning-level-mb>
<timestamp>09/01/2023 16:28:15</timestamp>
</post-alert-sim-warning>SIM Usage Limit Reached
<post-alert-sim-limit version="1" api-did="0000187012">
<passphrase>password</passphrase>
<iccid>1234567890123456789</iccid>
<cut-off-level-mb>2560</cut-off-level-mb>
<timestamp>09/01/2023 16:28:15</timestamp>
</post-alert-sim-limit>SIM Contract – One Month Remaining
<post-alert-contract-final-month version="1" api-did="0000187013">
<passphrase>password</passphrase>
<iccid>1234567890123456789</iccid>
</post-alert-contract-final-month>SIM Contract Expired
<post-alert-contract-expired version="1" api-did="0000187014">
<passphrase>password</passphrase>
<iccid>1234567890123456789</iccid>
</post-alert-contract-expired>Group Forecast Data Charge Warning Reached
<post-alert-group-data version="1" api-did="0000187015">
<passphrase>password</passphrase>
<group>group-code</group>
<threshold>2560</threshold>
<timestamp>09/01/2023 16:28:15</timestamp>
</post-alert-group-data>Group Forecast SMS Charge Warning Reached
<post-alert-group-sms version="1" api-did="0000187016">
<passphrase>password</passphrase>
<group>group-code</group>
<threshold>230</threshold>
<timestamp>09/01/2023 16:28:15</timestamp>
</post-alert-group-sms>Group Forecast Voice Charge Warning Reached
<post-alert-group-voice version="1" api-did="0000187017">
<passphrase>password</passphrase>
<group>group-code</group>
<threshold>500</threshold>
<timestamp>09/01/2023 16:28:15</timestamp>
</post-alert-group-voice>Group Out-of-Zone Charge Warning Reached
<post-alert-group-ooz version="1" api-did="0000187018">
<passphrase>password</passphrase>
<group>group-code</group>
<threshold>750</threshold>
<timestamp>09/01/2023 16:28:15</timestamp>
</post-alert-group-ooz>Forecast Total Group Charge Warning Reached
<post-alert-group-total version="1" api-did="0000187019">
<passphrase>password</passphrase>
<group>group-code</group>
<threshold>5400</threshold>
<timestamp>09/01/2023 16:28:15</timestamp>
</post-alert-group-total>Elements
Element | Description |
|---|---|
api-did (attribute) | Delivery ID generated by CSL. Unique reference for outbound API messages. Unsigned long integer (decimal). |
<passphrase> | Optional shared security string (max 16 alphanumeric characters). |
<iccid> | ICCID of the SIM. |
<group> | Group code associated with the alert. Distributor-specific. |
<timestamp> | UTC time the alert was recognised and actioned. Format: DD/MM/YYYY HH:MM:SS |
<warning-level-mb> | SIM usage warning level in MB (decimal). |
<cut-off-level-mb> | SIM usage cut-off level in MB (decimal). |
<threshold> | Monetary threshold triggering the alert. Expressed in the group’s tariff currency (decimal). |