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, 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.

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.

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	Email	DELIVERY   CLICK   OPEN   COMPLAINT   UNSUBSCRIBE
	Facebook	DELIVERY   MARKETING_OPT_IN   MARKETING_OPT_OUT
	Kakao - Alim	DELIVERY
	Kakao - Chingu	DELIVERY
	LINE	DELIVERY
	MMS	DELIVERY
	Mobile Push	DELIVERY
	RCS	DELIVERY   SEEN
	SMS	DELIVERY   CLICK
	Viber	DELIVERY   CLICK   SEEN
	Vkontakte	DELIVERY
	WhatsApp	DELIVERY   CLICK   SEEN   ACCOUNT_REGISTRATION   TEMPLATE_UPDATE
	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 & 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, take a look at https://www.infobip.com/docs/api/channels/sms/sms-messaging/outbound-sms/send-sms-message (and 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	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.

1. Click Create Subscription
2. Select the Channel that will be used for the subscription
3. (Optional) Depending on your use case:
   • Add a name for your subscription
   • Add any active Applications, Entities, Resources to the subscription
4. Select an existing Notification profile from the Notification Profiles section (or create new notification profile)

5. Define the Authentication settings in the Authentication settings dropdown (or create new authentication setting).
6. 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	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	Returns a single subscription specified by ID.	GET /subscriptions/1/subscription/{channel}/{subscriptionId}
Update subscription	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 to Developer 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. 

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	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	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.

1. Click Create Notification Profile.
2. Choose a profile ID that will be used to identify the notification profile.
3. Enter the webhook URL.
4. (Optional) Select an existing authentication setting from the Authentication settings dropdown (or create a new authentication).

5. 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	Returns a specific notification profile by ID.	GET /subscriptions/1/profiles/{profileId}
Get notification profiles paged	Returns a list of all notification profiles for your account with pagination.	GET /subscriptions/1/profiles
Update notification profile	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	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	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.

1. Click Create Authentication Settings.
2. Choose an authentication ID that will be used to identify the authentication setting.
3. Select the type of authentication you want to use:
   • Basic 
   • HMAC
   • OAuth
4. Apply your authentication credentials in the fields provided.
5. 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	Returns specific security settings item by ID.	GET /subscriptions/1/security/{authId}
Get security settings paged	Returns a list of security settings for your account with pagination.	GET /subscriptions/1/security
Update security settings	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	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 (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.  

Upload 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	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 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	Returns a page containing certificates details by filtering condition.	GET /subscriptions/1/certificates
Get certificate details by identifier	Returns a certificate details by certificate ID	GET /subscriptions/1/certificates/{certificateId}
Delete certificate	Deletes a single certificate	DELETE /subscriptions/1/certificates/{certificateId}
Get filtered certificates statuses page	Returns a page containing certificates statuses by filtering condition.	GET /subscriptions/1/certificates/status
Get certificate status by identifier	Returns a certificate status	GET /subscriptions/1/certificates/status/{certificateId}
Test a connection to a webhook	Performs connectivity check to provided webhook with the given certificate.	POST /subscriptions/1/certificates/test/webhook