Understanding webhook subscriptions
With webhook subscriptions, you receive all events for a category through a centralized configuration. They are ideal for real-time event processing, analytics pipelines, and monitoring systems where you want all events in one place instead of scattered across individual message requests.
For step-by-step setup instructions, see Manage webhook subscriptions.
What are webhook subscriptions [#what-are-webhook-subscriptions]
A webhook subscription delivers notifications about events on one channel or service to your webhook URL. You choose which events to receive, for example delivery reports, inbound messages, clicks, opens, and bounces. Webhook subscriptions have these characteristics:
- Real-time delivery: Infobip pushes each matching event to your webhook URL as it happens. You do not need to poll for events.
- Channel-level or service-level scope: You subscribe to a channel (SMS, Email, WhatsApp, and more) or a service (Registration, Mobile identity, Blocklist, and more), not to individual messages.
- Event filtering: Select the event types you need and narrow the scope with optional filters.
- Centralized routing: All selected events for a channel go to one webhook URL. To deliver the same events to more than one webhook, use subscription groups.
- Scalable and stateless: Each event is independent. No session or persistent connection is needed, and the system handles high-volume event streams efficiently.
How webhook subscriptions work [#how-webhook-subscriptions-work]
- Choose a category (Channels, Numbers and senders, or Tools), then select a specific channel or service.
- Specify which event types you want to receive (
DELIVERY,INBOUND_MESSAGE,CLICK, and more). - Provide your webhook URL through a notification profile.
- Optionally set filters (by application, entity, user, resource, and more). For inbound messages, you can also filter by keyword.
- Optionally assign a subscription group to deliver the same events to more than one webhook.
- A message is sent, delivered, replied to, or another tracked event fires on the subscribed channel.
- Checks that the channel or service matches.
- Checks that the event type is in your subscription.
- Checks that the filters match, if you set any.
- Runs this evaluation separately for each subscription group and selects one matching subscription per group.
- HTTP request to your webhook URL with event data.
- If subscriptions in more than one group match, each group receives its own notification.
- Automatic retries if your server does not respond immediately. Each group is retried independently.
- Verify the notification is authentic.
- Store the data and trigger business logic.
Subscription-notification-profile relationship [#subscription-notification-profile-relationship-how-webhook-subscriptions-work]
A subscription defines which events trigger notifications. A notification profile specifies where and how those notifications are delivered (your webhook URL, delivery settings, authentication). The resulting notifications are the actual HTTP POST requests sent when events occur. Every subscription must reference a notification profile, and this profile cannot be empty. For details on how these components relate and deletion dependencies, see Subscription hierarchy and deletion rules.
For a detailed breakdown of each component (notification profiles, authentication settings, certificates) and when to use them, see Subscription components.
Subscription groups [#subscription-groups-how-webhook-subscriptions-work]
A subscription group lets you deliver the same event to more than one webhook. Subscription groups follow these rules:
- One delivery per group: In each group, an event is delivered to one matching subscription.
- One copy per group: When subscriptions in different groups match the same event, each group receives its own copy.
- Default group: If you do not set a group, the subscription belongs to the default group.
For details and limits, see Subscription groups.
Subscription filters and scope [#subscription-filters-and-scope]
Subscriptions can include optional filters to narrow which events trigger notifications. If you leave filters empty, the subscription applies to all events in the selected category and channel.
| Filter | Description | Scope |
|---|---|---|
| Users | Events from a specific application user (basic authentication) | Legacy user-scoped filtering |
| Entity | Events for a specific entity type or ID | CPaaS X scoped filtering |
| Application | Events for a specific application ID | CPaaS X scoped filtering |
| Calls configuration | Events for a specific calls configuration | Voice events |
| Resources | Events for a specific communication resource (phone number, sender ID, email domain). For outbound traffic, matches the sender. For inbound traffic, matches the destination. | Number or sender-specific tracking |
| Keywords | Inbound messages that start with a keyword, for example ORDER. Add * to match a first word that starts with the keyword. See Filter inbound messages by keyword. | Inbound message events only |
Keywords are the only filter based on message content. The other filters match who sent or received the event and through which configuration.
Each subscription must be unique within its subscription group. You cannot create two subscriptions with the same combination of category and channel, event types, filter values, and subscription group. The system returns a validation error if you attempt to create a duplicate. To receive the same events at more than one webhook, assign the subscriptions to different subscription groups.
Choosing between subscriptions and per-message webhooks [#choosing-between-subscriptions-and-per-message-webhooks]
| Aspect | Webhook subscriptions | Per-message webhooks |
|---|---|---|
| Setup | Create once per channel | Configure in each API request |
| Routing | All events in one place | Route different messages to different URLs |
| Flexibility | Channel-level filtering | Message-level control |
| Operational burden | Low (one configuration) | High (configure every request) |
| Combining both | Use subscriptions for most events and per-message webhooks for special cases that need custom routing. | |
Use webhook subscriptions when
You want to process all events for a channel in one place, build real-time event pipelines or dashboards, need operational simplicity (configure once, apply everywhere), or handle high-volume event processing in multi-tenant systems.
Use per-message webhooks when
Different messages need different endpoints, you need message-level routing logic, or only some messages need webhooks.
Webhook URL override behavior [#webhook-url-override-behavior-choosing-between-subscriptions-and-per-message-webhooks]
You can define a webhook URL directly in individual message submit requests using fields like notifyURL, trackingURL, or webhookURL. This provides a quick way to receive event notifications for specific messages without configuring a subscription.
Setting a webhook URL in the message request overrides any configured subscriptions for that specific message. The message sends all notifications to the URL in the request, bypassing all subscription logic entirely. Even if you have an active subscription that normally receives these events, the message-level webhook takes precedence. This also applies to subscription groups: the event is delivered only to the URL in the request, not to any group.
When you provide webhook URLs in API requests, the system matches them against standalone notification profiles. If the system finds a match, it applies any configured advanced settings, certificates, or security configurations. If no matching standalone profile exists, the system forwards notifications to the URL without additional settings.
When to use message-level webhooks:
- Fast testing scenarios where you want to validate webhook behavior quickly
- Fallback cases where specific messages need different notification routing
- One-off notifications without subscription setup
For predictable routing, use subscriptions instead of message-level webhooks when:
- Running production systems that need centralized event handling
- If you already use subscriptions, adding message-level URLs creates conflicting routing
- Processing high-volume messaging where managing URLs per message is error-prone
Manage webhook subscriptions
Create, update, and delete subscriptions.
Available webhook events
Complete reference of events across all channels, numbers and senders, and tools.
Manage notification profiles
Define webhook URLs, delivery settings, and response validation.
Subscription groups
Deliver the same event to more than one webhook.