Manage webhook subscriptions

View as Markdown

A webhook subscription defines which events trigger notifications and how those notifications are delivered to your system. You can create, view, and manage subscriptions through the Infobip web interface or the Subscriptions API.

Prerequisites [#prerequisites]

To manage webhook subscriptions, you need:

Infobip account: Log in or register for an account with at least one communication channel enabled.
Communication resources: Phone numbers, sender IDs, or email domains to send messages through. See Resources and numbers overview for guidance on acquiring resources.
Webhook endpoint: A publicly accessible URL ready to receive notifications.
Notification profile: Defines where and how notifications are delivered. See Manage notification profiles.

For a conceptual overview of subscription components, see Understanding webhook subscriptions.

Create a subscription [#create]

Create a subscription for each channel from which you want to receive event notifications. Each subscription must include at least one event and a notification profile. To deliver the same event to more than one webhook, create a subscription for each webhook and assign each one to a different subscription group.

Log in to the Infobip web interface and go to Developer Tools > Subscriptions Management.
Select Create subscription.
On the Choose category screen, enter a subscription name. The name can contain any characters. The subscription ID is generated automatically. To use your own ID, replace it. For the subscription ID, use only letters, numbers, dashes, and underscores. You cannot change the ID after you create the subscription.

(Optional) In the Subscription group field, enter a group, for example analytics. Leave the field empty to use the default group. To send the same event to more than one webhook, create subscriptions with the same events and filters but a different subscription group. See Subscription groups.
Select a category:
- Channels: Email, Facebook, Kakao (Alim, Brand Messaging), LINE, Mobile push, RCS, SMS, MMS, TikTok, Viber, WhatsApp, Zalo, Voice and WebRTC, Open Channel, and Apple Messages for Business
- Numbers and senders: Registration, Mobile identity, and Number lookup
- Tools: Blocklist and Customer engagement / AgentOS
Then select Next.
On the Select events screen, choose the events you want to subscribe to and select Next. See Available webhook events for the complete list of events by channel.

NOTE
If you select the INBOUND_MESSAGE event and an inbound configuration is already defined at the number level, update that configuration and set "Apply subscription" as the forwarding action. See Inbound messages: subscription routing for details.
On the Set filters screen (optional), filter events by:
- Users: Events generated for specific users
- Entity: Entity ID representing a unique customer or department
- Application: Application ID representing a specific use case
- Resources: A sender name, number, domain, or other identifier. For outbound traffic, the resource filter matches the sender. For inbound traffic, it matches the destination.
- Keywords: For the INBOUND_MESSAGE event only. The subscription receives an inbound message only if the message starts with one of the keywords, for example ORDER. Add * to match a first word that starts with the keyword, for example ORDER*. Each keyword can be up to 50 characters long. Press Enter after each keyword. See Filter inbound messages by keyword.
You can combine multiple filters. A subscription triggers only when all filter conditions match. Any filter you leave empty acts as a wildcard and matches all values. For example, setting applicationId without entityId matches events from that application regardless of entity. Leave all filters empty to apply to all events in the selected category. Then select Next.
Select a notification profile or create a new one:
- If creating new, enter a name and webhook URL
- Optionally add response body regex or response regex to validate HTTP responses
IMPORTANT
A subscription must have a notification profile to function.
(Optional) Under Security settings, select an authentication setting or create a new one. See Manage authentication settings for details on each method.
(Optional) Apply a certificate for mutual TLS (mTLS) security.

(Optional) Configure advanced settings:

Setting	Range	Description
Max bucket size	1 to 2000	Maximum events per request
Window size	20 to 10000	Concurrent connections
Connect timeout	300 to 30000 ms	Connection timeout
Read timeout	1000 to 90000 ms	Read timeout
SSL protocols	TLS v1.2, v1.3	Enabled SSL protocols
Headers	Key-value pairs	Custom headers sent with requests
Rate limit	1 to 5000	Requests per second

Review the subscription summary and select Save.

Use the Create subscription API endpoint. Specify the channel in the request path.

You can create a new notification profile inline or reference an existing one by profileId.

To assign the subscription to a subscription group, set subscriptionGroupId. If you omit it, the subscription belongs to the default group. See Subscription groups.

To filter inbound messages by keyword, set keywords to an array of up to 255 keywords. See Filter inbound messages by keyword.

The subscriptionId cannot be changed after creation.

Deliver an event to more than one webhook [#deliver-an-event-to-more-than-one-webhook-create]

Create one subscription for each webhook and assign each subscription to a different subscription group. For how subscription groups work, see Subscription groups.

A subscription group can contain any characters, up to 255 characters. Use short names that describe the destination, for example analytics or audit-archive. Short names make each group easy to identify in the subscription list.

The subscription group is a string. An empty string is not a valid value. To use the default group, leave the field empty in the web interface or omit subscriptionGroupId in the API.

Log in to the Infobip web interface and go to Developer Tools > Subscriptions Management.
Select Create subscription.
On the Choose category screen, enter the subscription name. In the Subscription group field, enter the group for this subscription, for example analytics.
Complete the remaining steps in Create a subscription and select Save.
Repeat these steps for each destination. Select the same events and filters, and enter a different subscription group each time.

Set the subscriptionGroupId property in the Create subscription request. Specify the channel in the request path. The following requests create two subscriptions for the same channel that deliver delivery reports to two different webhooks:

Subscription for the analytics webhook

json

2 "subscriptionId": "analytics-delivery",

3 "name": "Delivery reports for analytics",

4 "subscriptionGroupId": "analytics",

5 "events": [

6 "DELIVERY"

7 ],

8 "profile": {

9 "profileId": "analytics-webhook"

10 }

11}

Subscription for the audit webhook

json

2 "subscriptionId": "audit-delivery",

3 "name": "Delivery reports for audit",

4 "subscriptionGroupId": "audit",

5 "events": [

6 "DELIVERY"

7 ],

8 "profile": {

9 "profileId": "audit-webhook"

10 }

11}

The Get subscriptions and Get subscription responses include subscriptionGroupId for subscriptions that belong to a group.

View or edit a subscription [#view-edit]

Log in to the Infobip web interface and go to Developer Tools > Subscriptions Management.
Open the Subscriptions tab and search for your subscription using the search bar.
Select the three-dot menu next to the subscription and choose:
- View: See a summary of your configuration
- Edit: Make changes to events, filters, subscription group, authentication, or notification profiles
NOTE
You cannot change the subscription category or channel.
Make your changes and select Save.

Use the Subscriptions API to:

Get all subscriptions for a channel. Filter by applicationId, entityId, resource, or user
Get a specific subscription by channel and subscription ID
Update the name, events, filters, keywords, resources, subscription group, or notification profile reference of a subscription

All operations require the channel in the request path.

IMPORTANT

When you update a subscription that belongs to a subscription group, include subscriptionGroupId in the request. If you omit it, the subscription moves to the default group.

The same applies to keywords. If you omit keywords or send it as null, the update removes all keywords from the subscription.

Change or remove a subscription group [#change-or-remove-a-subscription-group-view-edit]

You can change the subscription group of a subscription after you create it.

Web interface: Open the subscription, select Edit, and update the Subscription group field.
API: Send the updated subscriptionGroupId value in the Update subscription request.

To move a subscription back to the default group, clear the Subscription group field in the web interface. In the API, send subscriptionGroupId as null or omit it in the Update subscription request.

Delete a subscription [#delete]

Log in to the Infobip web interface and go to Developer Tools > Subscriptions Management.
Open the Subscriptions tab and search for your subscription using the search bar.
Select the three-dot menu next to the subscription and select Delete.

IMPORTANT

Deleting a subscription may impact other configured settings. Review Subscription hierarchy and deletion rules to understand deletion dependencies before proceeding.

Best practices for filters [#best-practices]

Define your coverage scope

Use filters to specify how broad or narrow to make the subscription. Setting an applicationId targets only events for that application. Leaving filters empty includes all events for the selected channel.

Ensure subscription uniqueness

Each subscription must be distinct within its subscription group. If you create two subscriptions with the same channel, event types, filter values, and subscription group, the system rejects the second one. See Which duplicate subscriptions are allowed.

Understand matching criteria

A subscription triggers only when all filter criteria match an incoming event. For example, if you set applicationId=AppB and entityId=Template123, only events from that exact combination match.

One event, one subscription per group

In each subscription group, an event matches only one subscription. This ensures consistent delivery, avoids duplicate processing, and makes troubleshooting easier. To deliver the same event to more than one webhook, place the subscriptions in different groups. See Subscription groups.

Related pages

Subscription groups
Deliver the same event to more than one webhook.

Available webhook events
Find events from all channels, number services, and platform tools.

Manage notification profiles
Configure where notifications are delivered.

Subscription hierarchy and deletion rules
Component relationships and deletion dependencies.

Was this page helpful?