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.

Log in to the Infobip web interface and go to Developer Tools > Subscriptions Management.
Open the Subscriptions tab. Use the search bar to find a specific subscription.
Select Create subscription.
On the Choose category screen, 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
Enter a subscription name and subscription ID. Use only letters, numbers, dashes, and underscores. 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 filter screen (optional), filter events by:
- User: Events generated for specific users
- Entity: Entity ID representing a unique customer or department
- Application: Application ID representing a specific use case
- Resource: A sender name, number, domain, or other identifier. For outbound traffic, the resource filter matches the sender. For inbound traffic, it matches the destination.
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.

The subscriptionId cannot be changed after creation.

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, authentication, or notification profiles
NOTE
You cannot change the subscription category or channel.
Make your changes and select Save.

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. If you create two subscriptions with the same channel, event types, and filter values, the system rejects the second one.

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

Each event matches only one subscription. This ensures consistent delivery, avoids duplicate processing, and makes troubleshooting easier.

Related pages

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

Manage notification profiles
Configure where notifications are delivered.

Manage authentication settings
Secure your webhook endpoints with Basic, HMAC, or OAuth.

Inbound message routing
Route inbound messages through subscriptions.

Subscription hierarchy and deletion rules
Component relationships and deletion dependencies.