Subscriptions

Once you have defined a sending strategy for your resources, consider how you want to manage subscriptions for event notifications in your scenario.

With CPaaS, you can use multiple communication channels, such as SMS, WhatsApp, and Email over HTTP API, along with Infobip products like Moments or Conversations. Every call or message sent through these channels triggers one or more notifications as events during the message lifecycle.

Events represent changes in the status of an outbound message or two-way communication. Notifications are the requests sent to the client's webhook when an event occurs. For example, a delivery report event is returned to the client when an SMS is delivered to the subscriber. Infobip also returns a delivery report notification on asynchronous APIs if an issue occurs during message processing on the Infobip platform.

At a minimum, most channels provide a delivery report, but other events, such as click or open, may also be available. Some notifications are not tied to a specific message or channel, such as an identity change on WhatsApp or an external API call in Moments.

Using the CPaaS X Subscriptions management API (opens in a new tab), you can define rules to specify whether you want to receive notifications for certain events. These rules are called subscriptions.

You can define one or more subscriptions for each channel in your use case. See Availability to view available channels.

Each channel should have at least one subscription rule defined if you want to receive event notifications, or more if different subsets of notifications need to be sent to different webhooks.

Subscription composition

A subscription defines the criteria for sending a notification. This can be general or highly specific. For example, you can configure your subscription to send notifications for specific events or based on other criteria such as applications or entities. If you want to configure a subscription for an entire channel and all events, leave the sending criteria undefined.

A subscription must include a notification profile, which is a set of rules that specifies where to send the notification and what settings to use. In a simple scenario, a notification profile might contain the client’s webhook URL and details about the expected content. You can also configure authentication settings to define how the system should authenticate when sending notifications to your webhook, though this is optional.

Both settings can be specified in full or you can reference an existing setup by its ID for reuse.

Here is an example of how authentication settings can be reapplied to notification profiles and how subscriptions use notification profiles to determine where to send notifications:

As with other CPaaS X building blocks, you can configure subscriptions using the Subscriptions management API (opens in a new tab).

The default method for creating subscriptions allows you to specify both the notification profile and authentication settings in a single request: https://{baseUrl}/subscriptions/v1/subscription/{channel}.

Create the notification profiles and subscriptions as a starting point, then define the security criteria if needed. It is recommended to protect your endpoint with at least basic authentication.

It is important to create a subscription for each channel from which you want to receive notifications.

Subscription scope

When creating subscriptions, you can use filters, such as applicationId or entitiyId, to define the range of events that trigger notifications. Understanding how these filters work together ensures that your subscriptions are meaningful and manageable.

1. Define event coverage

• You can determine how narrowly or broadly your subscription monitors events by applying specific filters. For example, specifying an applicationId focuses your subscription on events from just one application, while omitting it allows you to capture all events for that channel. This flexibility helps you tailor subscriptions to your exact needs.

2. Ensure subscription uniqueness

• Each subscription must be distinct from all others. You will encounter validation errors if you attempt to create two subscriptions that share the same criteria, such as the same event type on the same channel with identical filters. This prevents duplicate triggers and keeps your event-handling structure organized.

3. Match criteria

• A subscription is only triggered if every defined parameter matches the incoming event. If you set filters like applicationId=AppB and entityId=Template123, only an event from that specific application and entity will trigger the notification. This precise targeting ensures you receive only relevant updates.

4. One event, one subscription trigger

• Due to the uniqueness rule and exact matching, a single event will never trigger multiple identical subscriptions. This ensures consistent event delivery and simplifies troubleshooting.

By defining the scope of your subscriptions, you can focus only on the relevant events and maintain a transparent notification system. Whether you narrow your view to a single entity or broaden it to encompass an entire channel, these guidelines help ensure that your subscriptions deliver the right information at the right time.

Notification profile

Notification profiles define the rules that specify where to send notifications and what settings to apply. In simple terms, a notification profile may contain the client's webhook URL and details about the expected content. If authentication is required for your webhook, you can apply an authentication setting to the profile. Notification profiles can be configured through the API or using the web interface.

Authentication settings

Authentication settings define how the system will authenticate when sending notifications to your webhook. Creating an authentication setting is optional; it can be omitted if no authentication is required. These settings can be managed through the API or using the web interface.

Availability

The Subscriptions management API (opens in a new tab) supports the following channels and events:

TOPIC	CATEGORY	EVENT
Channels	Email	CLICK
		COMPLAINT
		DELIVERY
		OPEN
		UNSUBSCRIBE
	Facebook	DELIVERY
		MARKETING_OPT_IN
		MARKETING_OPT_OUT
	Kakao - Alim	DELIVERY
	Kakao - Chingu	DELIVERY
	LINE	DELIVERY
	MMS	CLICK
		DELIVERY
	Mobile Push	DELIVERY
	RCS	CLICK
		DELIVERY
		SEEN
	SMS	CLICK
		DELIVERY
	Viber	CLICK
		DELIVERY
		SEEN
	Vkontakte	DELIVERY
	WhatsApp	ACCOUNT_REGISTRATION
		CLICK
		DELIVERY
		PAYMENT_STATUS
		SEEN
		TEMPLATE_UPDATE
	Zalo	DELIVERY
	Voice and Video	APPLICATION_TRANSFER_FAILED
		APPLICATION_TRANSFER_FINISHED
		APPLICATION_TRANSFER_REQUESTED
		CALL_ESTABLISHED
		CALL_FAILED
		CALL_FINISHED
		CALL_MEDIA_CHANGED
		CALL_PRE_ESTABLISHED
		CALL_RECEIVED
		CALL_RECORDING_FAILED
		CALL_RECORDING_READY
		CALL_RECORDING_STOPPED
		CALL_RINGING
		CALL_STARTED
		CONFERENCE_COMPOSITION_FAILED
		CONFERENCE_COMPOSITION_FINISHED
		CONFERENCE_CREATED
		CONFERENCE_FINISHED
		CONFERENCE_RECORDING_FAILED
		CONFERENCE_RECORDING_READY
		CONFERENCE_RECORDING_STOPPED
		DIALOG_COMPOSITION_FAILED
		DIALOG_COMPOSITION_FINISHED
		DIALOG_CREATED
		DIALOG_ESTABLISHED
		DIALOG_FAILED
		DIALOG_FINISHED
		DIALOG_RECORDING_FAILED
		DIALOG_RECORDING_READY
		DIALOG_RECORDING_STOPPED
		DTMF_CAPTURED
		ERROR
		MACHINE_DETECTION_FAILED
		MACHINE_DETECTION_FINISHED
MEDIA_STREAM_FAILED
MEDIA_STREAM_FINISHED
PARTICIPANT_JOINED
PARTICIPANT_JOIN_FAILED
PARTICIPANT_JOINING
PARTICIPANT_MEDIA_CHANGED
PARTICIPANT_RECORDING_FAILED
PARTICIPANT_REMOVED
PARTICIPANT_STARTED_TALKING
PARTICIPANT_STOPPED_TALKING
PLAY_FINISHED
SAY_FINISHED
SPEECH_CAPTURED
TRANSCRIPTION
Numbers and Senders	Registration	BRAND_STATUS_UPDATE
		BRAND_VET_UPDATE
		CAMPAIGN_NETWORK_STATUS_UPDATE
		CAMPAIGN_STATUS_UPDATE
	Mobile Identity	SILENT_VERIFICATION
	Number Lookup	NUMBER_LOOKUP
Tools	Blocklist	BLOCK
		UNBLOCK

Set URL in a message submit request

When specifying the URL for receiving notifications directly in the message submit request, be aware that this method is not compatible with subscriptions and will override them. This approach offers simplicity and speed for cases where clients require a quick solution to receive all notifications without needing fine-grained control.

For example, review the NotifyURL and TrackingURL properties for setting the URL (opens in a new tab) (you can also refer to similar methods for other channels).

If you plan to use subscriptions, keep in mind that setting URLs in the message submit request will override the subscription rules.

Below is an example showing the difference between setting URLs directly in the message submit (fallback to URL) and setting them using the Subscriptions API (opens in a new tab) (Security #2 - Basic Auth). A message with the URL provided on submit will bypass the subscription logic entirely.

Manage subscriptions

You can create, modify, or delete subscriptions for your use case using the API (opens in a new tab) or Infobip web interface (opens in a new tab).

Create a subscription

API

To create a new subscription, use the following API request:

API	Information	Request
Create new subscription (opens in a new tab)	Creates a new subscription. You can provide an existing profile ID or submit a full definition of the profile and authentication settings if you wish to create new ones.	POST /subscriptions/1/subscription/{channel}

Web interface

1. In the web interface (opens in a new tab), navigate to Developer tools > Subscription management.

2. Select the Subscriptions tab to access the Subscriptions management area. This section displays all active subscriptions, including those created via API, along with channels, events, related profile IDs, and filters.

   

3. Use the Search box to filter existing subscriptions or select Create subscription to create a new subscription.

4. Choose the channel that you will use for the subscription.

5. (Optional) Depending on your use case:

   • Add a name for your subscription.
   • Add any active applications, entities, or resources to the subscription.

6. Select an existing notification profile from the Notification profiles section or create a new notification profile.

   NOTE

   A subscription must have a corresponding notification profile to function correctly.

7. Define the authentication settings in the Authentication settings dropdown or create a new authentication setting.

8. Save your subscription. It will then be available for immediate use.

   

Modify a subscription

You can make limited changes to your subscriptions, such as viewing the properties or updating event information.

API

To retrieve a single subscription, retrieve all subscriptions, or update a subscription, use the following API requests:

API	Information	Request
Get subscriptions (opens in a new tab)	Retrieves a list of all subscriptions for the specified channel with pagination. By default, the results are sorted in descending order by the creation date.	GET /subscriptions/1/subscription/{channel}
Get single subscription (opens in a new tab)	Retrieves a subscription specified by its ID.	GET /subscriptions/1/subscription/{channel}/{subscriptionId}
Update subscription (opens in a new tab)	Updates a subscription. You can modify its properties and provide a new profile ID to change the associated profile.	PUT /subscriptions/1/subscription/{channel}/{subscriptionId}

Web interface

1. In the web interface (opens in a new tab), navigate to Developer tools > Subscription management.

2. Search for the subscription you want to modify and select Edit.

3. Make the necessary changes and select Save to update the subscription.

   NOTE

   Changing the channel is not possible, but you can modify the channel events for the subscription. For example, you can subscribe to all channel events or select only a few that suit your use case.

   

Delete a subscription

If you want to delete a subscription, be aware that this action may impact other configured settings. It is important to review the Subscription hierarchy to understand the deletion rules. Be cautious, as deleting a subscription could affect other components tied to it.

API

To delete a subscription, use the following API request:

API	Information	Request
Delete subscription (opens in a new tab)	Deletes a subscription specified by its ID.	DELETE /subscriptions/1/subscription/{channel}/{subscriptionId}

Web interface

1. In the web interface (opens in a new tab), navigate to Developer tools > Subscription management.

2. Select the Subscriptions tab and search for the subscription you want to delete.

3. Select the three dots and choose Delete from the dropdown.

Manage notification profiles

You can create, modify, or delete notification profiles for your use case using the API (opens in a new tab) or Infobip web interface (opens in a new tab).

Create a notification profile

Depending on your use case, you may create a notification profile when setting up a new subscription. In this case, the notification profile will appear in the Notifications tab of the Subscriptions management area once the subscription is created.

You can create a standalone authentication setting for scenarios where you want to use a single authentication setting across multiple notification profiles

API

To create a new notification profile, use the following API request:

API	Information	Request
Create new notification profile (opens in a new tab)	Creates a new notification profile. You can provide an existing security settings ID, or submit a full definition if you wish to create a new one.	POST /subscriptions/1/profiles

Web interface

1. In the web interface (opens in a new tab), navigate to Developer tools > Subscription management.

2. Select the Notifications tab to access the Notification profiles area. This section displays all active notification profiles, including any created using the API, along with the profile ID, webhook URL, and authentication information.

   

3. Use the Search box to filter existing notifications profiles or select Create notification profile to create a new notification profile.

4. Choose a profile ID that will be used to identify the notification profile.

5. Enter the webhook URL.

6. (Optional) Select an existing authentication setting from the Authentication settings dropdown or create a new authentication setting.

   NOTE

   A notification profile must have a working authentication setting configured to function correctly. Refer to the Create authentication settings section for more information.

7. Select Save and your notification profile will be available immediately.

Modify a notification profile

You can make limited changes to your active notifications profiles, such as adapting the properties or modifying webhook URLs.

API

To retrieve a single notification profile, retrieve all notification profiles, or update a notification profile, use the following API requests:

API	Information	Request
Get single notification profile (opens in a new tab)	Retrieves a notification profile specified by its ID.	GET /subscriptions/1/profiles/{profileId}
Get notification profiles (opens in a new tab)	Retrieves a list of all notification profiles for your account with pagination.	GET /subscriptions/1/profiles
Update notification profile (opens in a new tab)	Updates the notification profile. You can modify its properties and provide an ID for the security settings if you wish to update them.	PUT /subscriptions/1/profiles/{profileId}

Web interface

1. In the web interface (opens in a new tab), navigate to Developer tools > Subscription management.

2. Select the Notifications profiles tab and search for the notification profile you want to modify.

3. Select the three dots, choose Edit from the dropdown, and make the necessary changes.

4. Select Save to update the notification profile.

Delete a notification profile

If you plan to delete a notification profile, be aware that this action may impact other configured settings. It is important to review the Subscription hierarchy to understand the deletion rules. Be cautious, as deleting a notification profile could affect other components tied to it.

API

To delete a notification profile, use the following API request:

API	Information	Request
Delete notification profile (opens in a new tab)	Deletes a notification profile specified by its ID.	DELETE /subscriptions/1/profiles/{profileId}

Web interface

1. In the web interface (opens in a new tab), navigate to Developer tools > Subscription management.

2. Select the Notifications profiles tab and search for the notification profile you want to delete.

3. Select the three dots and choose Delete from the dropdown.

   

Manage authentication settings

You can create, modify, and delete authentication settings for your use case using the API (opens in a new tab) or Infobip web interface (opens in a new tab).

Create authentication settings

Depending on your use case, you may choose to create an authentication setting when setting up a new notification profile. In this case, the authentication setting will appear in the Authentication settings tab of the Subscriptions management area once the authentication setting is created.

For scenarios where you want to use a single authentication setting across multiple notification profiles, you can create a standalone authentication setting.

API

To create a new authentication setting, use the following API request:

API	Information	Request
Create security settings (opens in a new tab)	Creates new security settings.	POST /subscriptions/1/security

Web interface

1. In the web interface (opens in a new tab), navigate to Developer Tools > Subscription management.

2. Select the Authentication settings tab to access the Authentication settings area. This section displays all active authentication settings, including any created using the API, along with the related ID and the authentication type.

   

3. Use the Search box to filter existing authentication settings or select Create authentication settings to get create a new authentication setting.

4. Choose an Authentication ID that will be used to identify the authentication setting.

5. Select the type of authentication you want to use:

   • Basic
   • HMAC
   • OAuth

6. Enter your authentication credentials in the provided fields.

7. Select Save and your authentication setting will be available immediately.

   

Modify authentication settings

You can make limited changes to your active authentication settings, such as updating the authentication type or modifying the authentication credentials.

API

To retrieve a single security setting, retrieve all security settings, or to update a security setting, use the following API requests:

API	Information	Request
Get single security setting (opens in a new tab)	Retrieves a security setting specified by its ID.	GET /subscriptions/1/security/{authId}
Get security settings (opens in a new tab)	Retrieves a list of all security settings for your account with pagination.	GET /subscriptions/1/security
Update security setting (opens in a new tab)	Updates the security setting.	PUT /subscriptions/1/security/{authId}

Web interface

1. In the web interface (opens in a new tab), navigate to Developer tools > Subscription management.

2. Select the Authentication settings tab and search for the authentication setting you want to modify.

3. Select the three dots, choose Edit from the dropdown, and make the necessary changes.

4. Select Save to update the authentication setting.

   

Delete authentication settings

If you plan to delete the authentication settings, be aware that this action may impact other configured settings. It is important to review the Subscription hierarchy to understand the deletion rules. Be cautious, as deleting an authentication setting could affect other components tied to it.

API

To delete an authentication setting, use the following API request:

API	Information	Request
Delete security settings (opens in a new tab)	Deletes a security setting specified by its ID.	DELETE /subscriptions/1/security/{authId}

Web interface

1. In the web interface (opens in a new tab), navigate to Developer tools > Subscription management.

2. Select the Authentication settings tab and search for the authentication setting you want to delete.

3. Select the three dots and choose Delete from the dropdown.

   

Subscription hierarchy

Due to the interconnected nature of subscriptions, notification profiles, and authentication settings, changes made to one component may affect others. For example, a subscription requires a notification profile to function, and a notification profile may include an authentication setting. This is particularly important when considering deletions.

The image below illustrates the deletion rules for subscriptions, notification profiles, and authentication settings.

Certificate management

Ensuring the security of your digital assets is critical, especially in a world where even a simple webhook can be exploited for malicious purposes. Infobip prioritizes security and aims to simplify its management by offering self-management of client certificates, enabling Mutual Transport Layer Security (mTLS).

Mutual Transport Layer Security (mTLS) allows both parties to authenticate each other during the initial SSL/TLS handshake. In standard TLS, only the client authenticates the server by verifying the server's certificate, but the server does not verify the client. This means the server trusts any client that connects, even though additional authentication mechanisms like username/password may be in place. With mTLS, both the server and the client exchange certificates, allowing each to verify the other’s authenticity.

In the scenario where Infobip sends events to a customer’s webhook, Infobip acts as the client, and the customer acts as the server. To enable mutual authentication, the customer must upload a certificate (opens in a new tab) (client certificate) to the Infobip platform. Customers can easily upload a new certificate without delay when the certificate expires.

Once uploaded, the certificate can be applied to a notification profile associated with the webhook to enable mutual authentication.

Upload a certificate

Once you have created your certificate according to your requirements, you can upload it to the Infobip platform using the following API request.

API	Information	Request
Upload certificate (opens in a new tab)	Uploads the certificate.	POST /subscriptions/1/certificates

Once the certificate has synced with the Infobip platform (you can verify this using the Get certificate status (opens in a new tab) API request), apply it to a subscription notification profile where a webhook is configured.

Any events sent to that webhook will now use the uploaded certificate to establish the mTLS connection.

Manage certificates

To help you manage your certificates, Infobip provides several APIs that allow you to retrieve certificates, test connections, and delete certificates for your configuration. This is particularly useful when certificates expire and need to be updated.

API	Information	Request
Get filtered certificate details page (opens in a new tab)	Returns a page containing certificate details based on filtering conditions.	GET /subscriptions/1/certificates
Get certificate details by identifier (opens in a new tab)	Returns 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 certificate statuses based on filtering conditions.	GET /subscriptions/1/certificates/status
Get certificate status by identifier (opens in a new tab)	Returns the status of a certificate by its ID.	GET /subscriptions/1/certificates/status/{certificateId}
Test connection to a webhook (opens in a new tab)	Performs a connectivity check to the provided webhook using the given certificate.	POST /subscriptions/1/certificates/test/webhook