Understanding webhook subscriptions

View as Markdown

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 automatically delivers notifications for all events that occur on a specific channel or service. You define which events matter to your application: delivery status, inbound replies, clicks, opens, and bounces. Infobip sends notifications to your webhook URL whenever those events occur.

Real-time: Events are pushed to you as they happen (not pulled on-demand).
Channel or service-level scope: Subscribe to one specific channel (SMS, Email, WhatsApp, and more) or service (Registration, Mobile Identity, Blocklist, and more), not individual messages.
Automatic delivery: All matching events are sent to your webhook URL as they occur.
Centralized routing: Your subscription endpoint receives selected events for the category.
Event filtering: Specify which event types you want (delivery, inbound, click, and more) and narrow scope with optional filters.
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]

You create a subscription

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

A message event occurs

A message is sent, delivered, replied to, or another tracked event fires on the subscribed channel.

Infobip evaluates the subscription

Does the channel or service match?
Is the event type in your subscription?
Do the filters match (if any)?

Infobip sends a webhook notification

HTTP request to your webhook URL with event data.
Automatic retries if your server does not respond immediately.

Your webhook receiver processes the event

Verify the notification is authentic.
Store the data and trigger business logic.

Subscription-notification-profile relationship [#subscription-notification-profile-relationship]

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

Learn more

Application, entity, and calls configuration filters let you scope subscriptions to specific customers or configurations in multi-tenant platforms. See Webhook subscriptions in CPaaS X for detailed setup. For resource types, see Resources and numbers overview.

NOTE

Each subscription must be unique. You cannot create two subscriptions with the same combination of category and channel, event types, and filter values. The system returns a validation error if you attempt to create a duplicate.

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)
Combine?	Use subscriptions for most events + 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]

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.

IMPORTANT

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.

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

Related pages

Available webhook events
Complete reference of events across all channels, numbers and senders, and tools.

Manage webhook subscriptions
Create, update, and delete subscriptions.

Manage notification profiles
Define webhook URLs, delivery settings, and response validation.

Subscription hierarchy and deletion rules
Component relationships and deletion dependencies.

Inbound message routing
Configuration hierarchy and decision flows for inbound messages.

Manage event formats
Select static or adaptive event payload formats by channel.