Subscriptions Management
Once you have defined a sending strategy for your resources you should then think about how you would like to manage subscriptions for event notifications in your scenario.
With CPaaS, you can use multiple communication channels with your customers such as SMS, WhatsApp, Email over HTTP API, and also Infobip products like Moments or Conversations.
Every call or message submitted by these channels will cause one or more notifications to be sent as events during the lifecycle of the message.
Events are essentially a change of status of an outbound message or two-way communication, and notifications are the requests to the clients' webhook when the event happens. A simple example of this would be a Delivery Report event that is returned to the client when an SMS is delivered to the subscriber. Infobip will also return a Delivery Report notification on our asynchronous APIs if something goes wrong during message processing on the Infobip platform.
As a minimum, most channels will provide a Delivery Report but you may see other events such as Click or Open. There are sometimes notifications that are not related to a specific message, or specific channel. For example, Identity Change on WhatsApp, or the External API call in Moments.
With the CPaaS X Subscriptions Management API (opens in a new tab), you define rules to determine if you want to receive notifications about events that happen or not. These rules are known as Subscriptions.
You can define one or more subscriptions for each of the channels in your use case. Take a look at Availability to see available channels.
Every channel should have at least one subscription rule defined if you want to receive notifications about events happening on it, or more if different subsets of notifications need to be sent to different webhooks.
Subscription Composition
What makes up a Subscription? Subscriptions define the sending criteria for a notification. This can be generic or very specific. For example, you could configure your subscription to only send notifications for a certain type of event, or other criteria like Applications and Entities. If you want subscriptions to be configured for a whole channel and all events, then simply do not define sending criteria.
A Subscription must contain a Notification profile which is a set of rules that tell the system where to send the notification and what settings should be used. In a simple scenario, a notification profile could contain the client's webhook URL and information about the content that is expected. A Notification Profile can be configured with Authentication settings in order to tell the system how to authenticate when sending the notification to your webhook, though this is not mandatory.
Both settings can be specified in full, or you could reference (i.e. reuse) a pre-existing setup by its ID.
Here is an example of how Authentication settings can be re-applied to Notifications profiles, and how Subscriptions are using Notification profiles for knowing where to send the notification:
As with other CPaaS X building blocks, configure Subscriptions using the Subscriptions Management API (opens in a new tab).
The default method for creating Subscriptions allows you to also specify Notification profile and Authentication settings in one request: https://{baseUrl}/subscriptions/v1/subscription/{channel}
As a starting point, you should first create the Notifications Profiles and Subscriptions, and then define the security criteria if needed (it is advised to always protect your endpoint with at least Basic authentication).
It is important to create a Subscription for every channel you want to receive notifications.
It is possible to manage Notification Profiles separately from Subscriptions, and Authentication settings separately from Profiles. This option allows you to create those objects separately first and then reuse them referencing by ID when creating new Subscriptions.
Notifications Profiles
Notification profiles are a set of rules that tell the system where to send the notification and what settings should be used. In the simplest terms, a notification profile could contain the client's webhook URL and information about the content that is expected. You can apply an authentication setting to the profile if you require authentication on your webhook. You can configure notification profiles via the API or using the web interface.
Authentication Settings
Authentication settings tell the system how to authenticate when sending the notification to your webhook. It is up to you whether to create an authentication setting; if no authentication is required then it is not required. This can be managed via the API or using the web interface.
Availability
The Subscriptions Management API is available for use with the following channels and events:
TOPIC | CATEGORY | EVENT |
---|---|---|
Channels | DELIVERY | |
CLICK | ||
OPEN | ||
COMPLAINT | ||
UNSUBSCRIBE | ||
DELIVERY | ||
MARKETING_OPT_IN | ||
MARKETING_OPT_OUT | ||
Kakao - Alim | DELIVERY | |
Kakao - Chingu | DELIVERY | |
LINE | DELIVERY | |
MMS | DELIVERY | |
CLICK | ||
Mobile Push | DELIVERY | |
RCS | DELIVERY | |
SEEN | ||
SMS | DELIVERY | |
CLICK | ||
Viber | DELIVERY | |
CLICK | ||
SEEN | ||
Vkontakte | DELIVERY | |
DELIVERY | ||
CLICK | ||
SEEN | ||
ACCOUNT_REGISTRATION | ||
TEMPLATE_UPDATE | ||
PAYMENT_STATUS | ||
Zalo | DELIVERY | |
Voice and Video | DTMF_CAPTURED | |
CALL_ESTABLISHED | ||
CALL_PRE_ESTABLISHED | ||
CALL_MEDIA_CHANGED | ||
CALL_FINISHED | ||
CALL_FAILED | ||
CALL_RECEIVED | ||
CALL_STARTED | ||
CALL_RECORDING_FAILED | ||
CALL_RECORDING_READY | ||
CALL_RECORDING_STOPPED | ||
CONFERENCE_RECORDING_FAILED | ||
CONFERENCE_RECORDING_READY | ||
CONFERENCE_RECORDING_STOPPED | ||
CALL_RINGING | ||
CONFERENCE_CREATED | ||
CONFERENCE_FINISHED | ||
ERROR | ||
PARTICIPANT_MEDIA_CHANGED | ||
PARTICIPANT_JOIN_FAILED | ||
PARTICIPANT_JOINED | ||
PARTICIPANT_JOINING | ||
PARTICIPANT_RECORDING_FAILED | ||
PARTICIPANT_REMOVED | ||
PARTICIPANT_STARTED_TALKING | ||
PARTICIPANT_STOPPED_TALKING | ||
PLAY_FINISHED | ||
CONFERENCE_COMPOSITION_FAILED | ||
CONFERENCE_COMPOSITION_FINISHED | ||
SAY_FINISHED | ||
SPEECH_CAPTURED | ||
MACHINE_DETECTION_FINISHED | ||
MACHINE_DETECTION_FAILED | ||
MEDIA_STREAM_FAILED | ||
MEDIA_STREAM_FINISHED | ||
APPLICATION_TRANSFER_REQUESTED | ||
APPLICATION_TRANSFER_FAILED | ||
APPLICATION_TRANSFER_FINISHED | ||
DIALOG_CREATED | ||
DIALOG_ESTABLISHED | ||
DIALOG_FAILED | ||
DIALOG_FINISHED | ||
DIALOG_RECORDING_FAILED | ||
DIALOG_RECORDING_READY | ||
DIALOG_RECORDING_STOPPED | ||
DIALOG_COMPOSITION_FAILED | ||
DIALOG_COMPOSITION_FINISHED | ||
TRANSCRIPTION | ||
Numbers and Senders | Registration | BRAND_STATUS_UPDATE |
BRAND_VET_UPDATE | ||
CAMPAIGN_STATUS_UPDATE | ||
CAMPAIGN_NETWORK_STATUS_UPDATE | ||
Mobile Identity | SILENT_VERIFICATION | |
Number Lookup | NUMBER_LOOKUP | |
Tools | Blocklist | BLOCK |
UNBLOCK |
Set URL on Message Submit
Be aware of the simple method of specifying the URL for receiving notifications in message submit, which is not compatible with Subscriptions and will override them. This gives clients simplicity and speed if they have an additional use case and need a simple and quick solution to receive all notifications and do not require fine-grained rules.
As an example, see here (opens in a new tab) (and other similar methods for other channels) for NotifyURL
and TrackingURL
properties.
If you are planning to use Subscriptions, you should always keep in mind that setting URLs in message submit will override them.
Take a look below to see an example where URLs were set in the message on submit (fallback to URL) or set up over Subscriptions API (Security #2 - Basic Auth). You can see that message with the URL provided on submit will skip the Subscriptions logic completely.
Create Subscription
Use the API or web interface to create a subscription for your use case.
API
The following API can be used to create a new subscription.
API | Information | Request |
---|---|---|
Create new subscription (opens in a new tab) | This method will create a new subscription.You can provide an ID of an existing profile, or submit full definition of the profile and authentication settings if you want to create new ones. | POST /subscriptions/1/subscription/{channel} |
Web Interface
To create a new subscription from the web interface, navigate to Developer Tools > Subscription Management and select Subscriptions tab to access the Subscriptions Management area.
The Subscriptions management area displays all active subscriptions (including any you have created via API), channels, events, related profile ID and filters.
Use the search box to filter existing subscriptions or click Create Subscription to create a new subscription.
-
Click Create Subscription
-
Select the Channel that will be used for the subscription
-
(Optional) Depending on your use case:
- Add a name for your subscription
- Add any active Applications, Entities, Resources to the subscription
-
Select an existing Notification profilefrom the Notification Profiles section (or create new notification profile)
NoteTo work correctly, a Subscription must have a corresponding Notification profile.
-
Define the Authentication settingsin the Authentication settings dropdown (or create new authentication setting).
-
Save your subscription. It will then be available to use immediately.
Manage Subscriptions
You can manage your subscriptions through the web interface or using the API.
Edit
You can make limited changes to your subscriptions such as adapting properties or modifying events information this can be done using the API or web interface.
API
The following APIs can be used to edit a subscription.
API | Information | Request |
---|---|---|
Get subscriptions paged (opens in a new tab) | Returns a list of all subscriptions for the specified channel with pagination. By default result is sorted descending by creation date. | GET /subscriptions/1/subscription/{channel} |
Get single subscription (opens in a new tab) | Returns a single subscription specified by ID. | GET /subscriptions/1/subscription/{channel}/{subscriptionId} |
Update subscription (opens in a new tab) | This method allows you to update the subscription. You can change its properties, and also provide an ID of a profile if you wish to change it. | PUT /subscriptions/1/subscription/{channel}/{subscriptionId} |
Web Interface
To edit an existing subscription, navigate toDeveloper Tools > Subscription Management, search for the subscription you wish to edit and click Edit. Make the changes you need and click Save to update the subscription.
It is not possible to change the channel but you can change the channel events for the subscription, i.e., change subscribe to all channel events or choose a few channel events for your use case.
Delete
It is possible to delete subscriptions using API or web interface however doing so can impact other settings that you have configured.
We recommend you get accustomed to the rules for deletion under Subscription Hierarchy.
API
Use the delete subscription API to delete a subscription.
API | Information | Request |
---|---|---|
Delete subscription (opens in a new tab) | This method will delete the subscription specified by ID. | DELETE /subscriptions/1/subscription/{channel}/{subscriptionId} |
Web Interface
If you need to delete a subscription, you can do so on the Infobip platform. However, before you complete this step there are a few important considerations to remember.
Be careful when deleting subscriptions because the action may impact other settings. Take a look at Subscription Hierarchy to learn more about the deletion rules for subscriptions, notification profiles, and authentication settings.
If you still want to delete a subscription then search for the subscription you wish to delete and click Delete.
The subscription will be deleted.
Create Notification Profile
Use the API or web interface to create notification profiles for your use case.
Depending on your use case you may decide to create a notification profile when you create a new subscription in which case the notification profile will be visible in the Notifications tab of the subscription management area when the subscription is created.
To create a separate/standalone notification profile for scenarios like using a single notification profile for multiple subscriptions then you can create an individual notification profile. Read on to learn more.
API
The following API can be used to create a new notification profile.
API | Information | Request |
---|---|---|
Create new notification profile (opens in a new tab) | This method will create a new notification profile. You can provide an ID of existing security settings if you wish to reuse them, or submit a full definition if you want to create a new one. | POST /subscriptions/1/profiles |
Web Interface
To create a new notification profile using the web interface, navigate to Developer Tools > Subscription Management and select Notifications tab to access the Notification profiles area.
The Notification profiles area displays all active notification profiles (including any you have created via API), related profile ID, webhook URL, and authentication information.
Use the search box to filter existing notifications profiles or click Create Notification Profile to get started.
-
Click Create Notification Profile.
-
Choose a profile ID that will be used to identify the notification profile.
-
Enter the webhook URL.
-
(Optional) Select an existing authentication setting from the Authentication settings dropdown (or create a new authentication).
NoteTo work correctly a notification profile must have a working authentication setting configured. Take a look at the Create Authentication Settings section to learn more.
-
Click Save and your notification profile will be available immediately.
Manage Notification Profiles
You can manage your notification profiles through the web interface or using the API.
Edit
Make limited changes to your active notifications profiles such as adapting properties or modifying webhook URLs. This can be done using the API or web interface.
API
The following APIs can be used to edit notification profiles.
API | Information | Request |
---|---|---|
Get single notification profile (opens in a new tab) | Returns a specific notification profile by ID. | GET /subscriptions/1/profiles/{profileId} |
Get notification profiles paged (opens in a new tab) | Returns a list of all notification profiles for your account with pagination. | GET /subscriptions/1/profiles |
Update notification profile (opens in a new tab) | This method allows you to update the notification profile. You can change it’s properties, and also provide an ID of security settings if you wish to change them. | PUT /subscriptions/1/profiles/{profileId} |
Web Interface
To edit an existing notification profile, navigate to Developer Tools > Subscription Management and click Notifications profiles tab, search for the notification profile you wish to edit and click Edit. Make the changes you need and click Save to update the notification profile.
Delete
It is possible to delete notification profiles using API or web interface however doing so can impact other settings that you have configured.
We recommend you get accustomed to the rules for deletion under Subscription Hierarchy.
API
Use the delete notification profile API to delete a notification profile.
API | Information | Request |
---|---|---|
Delete notification profile (opens in a new tab) | This method will delete the notification profile specified by ID. | DELETE /subscriptions/1/profiles/{profileId} |
Web Interface
If you need to delete a notification profile, you can do so on the Infobip platform. However, before you complete this step there are a few important considerations to remember.
Be careful when deleting notification profiles because the action may impact other settings. Take a look at Subscription Hierarchy to learn more about the deletion rules for subscriptions, notification profiles, and authentication settings.
If you still want to delete a notification profile then search for the notification profile you wish to delete and click Delete.
Create Authentication Setting
Use the API or web interface to create authentication settings for your use case.
Depending on your use case you may decide to create an authentication setting when you create a new notification profile in which case the authentication setting will be visible in the Authentication settings tab of the subscription management area when the authentication setting is created.
To create separate/standalone authentication settings for scenarios like using a single authentication setting for multiple notification profiles then read on to learn more.
API
The following API can be used to create a new authentication setting.
API | Information | Request |
---|---|---|
Create new security settings (opens in a new tab) | This method will create new security settings. | POST /subscriptions/1/security |
Web Interface
To create a new authentication setting using the web interface, navigate to Developer Tools > Subscription Management and select the Authentication Settings tab to access the Authentication settings area.
The Authentication settings area displays all active authentication settings (including any you have created via API), related ID, and authentication type.
Use the search box to filter existing authentication settings or click Create Authentication Settings to get started.
- Click Create Authentication Settings.
- Choose an authentication ID that will be used to identify the authentication setting.
- Select the type of authentication you want to use:
- Basic
- HMAC
- OAuth
- Apply your authentication credentials in the fields provided.
- Click Save and your authentication setting will be available immediately.
Manage Authentication Settings
You can manage your authentication settings through the web interface or using the API.
Edit
Make limited changes to your active authentication settings such as changing authentication type or authentication credentials. This can be done using the API or web interface.
API
The following APIs can be used to edit authentication settings.
API | Information | Request |
---|---|---|
Get single security settings (opens in a new tab) | Returns specific security settings item by ID. | GET /subscriptions/1/security/{authId} |
Get security settings paged (opens in a new tab) | Returns a list of security settings for your account with pagination. | GET /subscriptions/1/security |
Update security settings (opens in a new tab) | This method allows you to update the security settings. | PUT /subscriptions/1/security/{authId} |
Web Interface
To edit an existing authentication setting, navigate to Developer Tools > Subscription Management and click the Authentication settings tab, search for the authentication setting you want to edit, and click Edit. Make the changes you need and click Save to update the authentication setting.
Delete
It is possible to delete authentication settings using API or web interface however doing so can impact other settings that you have configured.
We recommend you get accustomed to the rules for deletion under Subscription Hierarchy.
API
Use the delete security settings API to delete an authentication setting.
API | Information | Request |
---|---|---|
Delete Security Settings (opens in a new tab) | This method will delete the security settings item by ID. | DELETE /subscriptions/1/security/{authId} |
Web Interface
If you need to delete an authentication setting, you can do so in the Infobip platform. However, before you complete this step there are a few important considerations to remember.
Be careful when deleting authentication settings because the action may impact other settings. Take a look at Subscription Hierarchy to learn more about the deletion rules for subscriptions, notification profiles, and authentication settings.
If you still want to delete an authentication setting then search for the authentication setting you wish to delete and click Delete.
Subscription Hierarchy
Due to the interconnected nature of Subscriptions, Notification Profiles and Authentication settings, changes you make can impact other things.
For example, a Subscription must have a Notification Profile to be able to work but a Notification Profile may have an Authentication setting.
This is particularly relevant if you want to delete settings. The image below shows the deletion rules for Subscriptions, Notification Profiles, and Authentication settings.
Certificate Management
Your digital asset security is paramount in today's world where you want to have control over who has access to those assets, even to a simple webhook that could be exploited for nefarious purposes.
Infobip always has this in mind and is looking for ways to make security simpler to manage. We do this by offering self-management of client certificates, which enable Mutual Transport Layer Security (mTLS).
Mutual Transport Layer Security (mTLS) allows two parties to authenticate each other during the initial connection of an SSL/TLS handshake. With standard TLS it is only the client who authenticates the server by checking the certificate the server provides; the client does not have to provide a certificate to the server to prove its authenticity. This means the server is essentially trusting any client who connects with it, though it may have additional authentication mechanisms like username/password. With mTLS, both the Server and the Client provide certificates so each can check each other out.
In the scenario of Infobip sending events to a customer's webhook, Infobip is the Client and the customer is the Server so if the Customer wants to mutually authenticate Infobip a certificate needs to be uploaded to the Infobip Platform.
Previously Customers would provide a certificate to Infobip and Infobip would provision it manually on its Platform, which would take time and require management when a certificate expired. Now Customers can upload the certificate (opens in a new tab) (client certificate) to Infobip immediately and start using it in a matter of minutes. Likewise, when the certificate expires, they can simply upload a new one.
Once a certificate is uploaded it can be applied to a Notification Profile with the webhook for mutual authentication.
mTLS works on the connection level between Infobip and its Customers and is different from the authorization that works on the Application level when a Username/Password, OAuth and HMAC is used in the Subscription Authentication Settings module.
Upload Certificate
The following information assumes that you have already created a security certificate for your configuration. It is advisable to refer to your IT infrastructure team if you need to create a certificate.
Once you have created your certificate according to your own requirements, you can upload your certificate to the Infobip platform using the Upload Certificate API request.
API | Information | Request |
---|---|---|
Upload Certificate (opens in a new tab) | Upload security certificate. | POST /subscriptions/1/certificates |
Once the certificate has synced in the Infobip platform (you can verify by using the Get certificate status by identifier (opens in a new tab) request), apply it to a Subscription Notification Profile where a webhook is configured.
Any events that are sent to that webhook will now use the certificate you uploaded to set up the mTLS connection.
Manage Certificate
To enable you to manage your certificates, Infobip has made available a number of APIs where you can get certificates, test connections and delete certificates for your configuration. This is useful for situations when certificates expire and you want to update them.
API | Information | Request |
---|---|---|
Get filtered certificate details page (opens in a new tab) | Returns a page containing certificates details by filtering condition. | GET /subscriptions/1/certificates |
Get certificate details by identifier (opens in a new tab) | Returns a certificate details by certificate ID | GET /subscriptions/1/certificates/{certificateId} |
Delete certificate (opens in a new tab) | Deletes a single certificate | DELETE /subscriptions/1/certificates/{certificateId} |
Get filtered certificates statuses page (opens in a new tab) | Returns a page containing certificates statuses by filtering condition. | GET /subscriptions/1/certificates/status |
Get certificate status by identifier (opens in a new tab) | Returns a certificate status | GET /subscriptions/1/certificates/status/{certificateId} |
Test a connection to a webhook (opens in a new tab) | Performs connectivity check to provided webhook with the given certificate. | POST /subscriptions/1/certificates/test/webhook |
Be careful when deleting certificates. You will not be able to delete a certificate linked to a Notification Profile, therefore update the Notification Profile before deleting.