Version: v2.0

Notifications

Available Notifications#

Currently Truphone Connect supports notifcations via a webhook registration. This process is not global for all SIMs and therefore each SIM object will need to be registered in order to receive its notifications.

Currently Connect provides support for two types of notifications: SUBSCRITPION_END and USAGE_THRESHOLD.

Usage Threshold Payload Example#

This type of notifications are triggered upon 80% of usage is reached.

{
"id": "1234-56789",
"type": "USAGE_THRESHOLD",
"iccid": "893000000002391231",
"subscription_id": "ZHNhc2Rhc2Q=",
"threshold": 80
}

Subscription End Payload Example#

This type of notifications are triggered upon full depletion of a plan or when it passes its expiration date.

{
"id": "1234-56789",
"type": "SUBSCRIPTION_END",
"iccid": "893000000002391231",
"subscription_id": "ZHNhc2Rhc2Q="
}

1. Registering Webhook#

In order to receve notifications the first step is to register a webhook onto a SIM resource passing the intentded notification type. At the moment only one request per type is supported.

Note: Currently notification work per SIM resource so each SIM needs to be registered to have a webhook, the webhook URL can be the same across all the SIMs

Example Request#

curl -X PUT \
https://services.truphone.com/connect-api/v2/sims/8944474600000109251/notifications/SUBSCRIPTION_END \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
-H 'X-Correlation-ID: unique-id-from-requester-123'
-d '{
"webhook_url": "http://acme-flights.com/notifications/handler"
}'

2. Receiving Notification#

When the events happen a payload will be sent to the registered webhook.

Example Payload#

{
"id": "1234-56789",
"type": "SUBSCRIPTION_END",
"iccid": "893000000002391231",
"subscription_id": "ZHNhc2Rhc2Q="
}

3. Unregistering Webhook#

At any time it's possible to stop receiving notifications for any specific SIM using the delete SIM preferences API

Example Request#

curl -X DELETE \
https://services.truphone.com/connect-api/v2/sims/8944474600000109251/notifications/SUBSCRIPTION_END \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H 'Cache-Control: no-cache' \
-H 'Content-Type: application/json' \
-H 'X-Correlation-ID: unique-id-from-requester-123'