Skip to main content

Notifications

Available Notifications​

Currently 1GLOBAL Connect supports notifications 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 three types of notifications: SUBSCRITPION_END, USAGE_THRESHOLD and DOWNLOAD_PROGRESS .

Usage Threshold Payload Example​

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

{
  "id": "1234-56789",
  "type": "USAGE_THRESHOLD",
  "iccid": "893000000002391231",
  "subscription_id": "ZHNhc2Rhc2Q=",
  "threshold": 80,
  "expiration_date": "2024-10-14T04:05:38Z",
  "current_balance": 1073741824
}

Subscription End Payload Example​

These 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=",
  "expiration_date": "2024-10-14T04:05:38Z",
  "current_balance": 0
}

Download Progress Payload Example​

These type of notifications are triggered whenever there's a change of status in a SIM profile

{
  "id": "1234-56789",
  "iccid": "8944478600004958824",
  "eid" : "123456789",
  "type": "DOWNLOAD_PROGRESS",
  "download_progress_step": "BPP_INSTALLATION",
  "notification_point_description:" "BPP Installation",
  "notification_status": "SUCCESS"
}

1. Registering Webhook​

In order to receive notifications, the first step is to register a webhook onto a SIM resource passing the intended notification type. Currently, only one request per type is supported.

For increased security, Basic Authentication could be used when sending notifications to webhooks. For more information and how to configure it, please contact our services.

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'