Reporting webhooks

View as Markdown

Webhooks let you receive event notifications from Infobip across more than 15 messaging channels and platform services. Infobip sends a POST request to your endpoint the moment an event occurs: delivery status, clicks, read receipts, inbound messages, and more.

Use webhooks when you need real-time event processing, want to store data in your own systems, or are building a multitenant platform. Two configuration methods are available:

Per-request: Specify the webhook URL when sending each message through the API.
Webhook subscriptions: Configure channel-level notifications with filtering and security through Subscriptions Management.

When you just need analytics or scheduled exports, the built-in reporting tools require less setup.

Coverage

For the complete catalog of all event types across all supported channels, services, and platform events, see the Event subscriptions reference.

Webhooks are supported for the following channels and platform services:

Webhooks do not store data. Events are pushed in real time and Infobip does not retain them.

Configuration methods

You can configure webhooks in two ways:

Method	Description	Best for
Per-request	Specify the webhook URL when sending each message. The parameter depends on the API version: • `deliver`: use `url`, `contentType`, `notify` • Legacy: use `notifyUrl` and `notifyContentType` See your channel API reference for exact parameters.	Message-level control; different endpoints per message
Webhook subscriptions	Configure channel-level subscriptions through the Subscriptions Management web interface or the Subscriptions API. Set your endpoint URL, security settings, and event filters per channel. Events arrive at your URL in the payload format defined by the channel webhook schema.	Scalable setups requiring filtering, security, or separate endpoints per channel

For the full subscription setup guide, including notification profiles, security settings, and available events per channel, see the Subscriptions documentation.

Per-request or subscriptions [#per-request-or-subscriptions]

Aspect	Per-request webhooks	Subscriptions
Setup	Specify URL in each API request	Configure once through the Subscriptions API
Filtering	None at webhook level	By application, entity, user, resource
Security	Standard HTTPS	Built-in authentication (Basic, HMAC, OAuth) and mTLS

For a detailed comparison, see Choosing between subscriptions and per-message webhooks.

Webhook event types

Webhook payloads differ by event type and channel. The event type determines what triggered the webhook and what fields the payload contains.

Infobip webhooks fall into two broad categories:

Messaging events: Triggered by activity on a message you sent or received: a status change, an incoming reply, or a recipient interaction. Available event types and payload fields vary by channel.
Platform service events: Triggered when an asynchronous service request completes (Mobile Identity, Number Lookup, Blocklist). These use service-specific schemas.

The following are the most common event categories. For the complete list of all events by channel, see Available webhook events.

Event type	What triggers it	Availability	Example schema
`DELIVERY`	Message reaches a final status (delivered, failed, expired, rejected). Includes status, error codes, timing, pricing, and fields from your original request.	All supported messaging channels	SMS delivery reports
`INBOUND_MESSAGE`	A subscriber sends a message to a number or address you own. Includes sender, content, timestamp, and pricing.	Channels that support two-way messaging	SMS inbound messages
`CLICK`	A recipient clicks a shortened URL in your message. Includes the URL, recipient device type, OS, and geolocation. Requires URL shortening and tracking to be enabled.	Channels that support URL tracking	SMS tracking notifications
`SEEN`	A recipient views your message (read receipt).	WhatsApp, RCS, Viber Business Messages, Kakao Brand Message	WhatsApp seen reports
Platform service results	An asynchronous service request completes (Mobile Identity verification, Number Lookup, Blocklist change). Schemas vary by service.	Mobile Identity, Number Lookup, Blocklist	Blocklist events

Common fields across delivery webhooks [#common-fields]

Delivery webhooks contain system-generated fields (delivery status, error details, timing, network codes, pricing) plus optional fields from your send request. While full schemas are in the API reference, these fields appear across most delivery webhook payloads:

Field	Description
`messageId`	Unique message identifier for matching and tracking. Always present. Returns your custom value if set, or the auto-generated Infobip ID otherwise.
`bulkId`	Bulk identifier for grouped messages or multiple recipients. Behavior varies by API version. Auto-generated and always present in the `deliver` APIs. Present only if set in legacy APIs.
`callbackData`	Custom data: order IDs, references, or any metadata. Present if set in the request. Absent if omitted. The maximum length depends on the channel: see Data payload.
`campaignReferenceId`	Campaign tracking ID for analytics and organization. Present if set in the request. Absent if omitted.
`entityId` and `applicationId`	Multitenant entity and application identifiers. Behavior varies by API version: see your channel API reference for details.

contentType sets the delivery report payload format (application/json or application/xml). See the SMS API reference for details.

Push retry cycle

If your endpoint is unavailable, Infobip retries using this formula:

1 min + (1 min × retryNumber²)

Retries are numbered from 0, so retryNumber is 0 for the first retry. The maximum number of retries is 20. The last retry occurs 41 hours and 30 minutes after the initial attempt. If your endpoint is unavailable for the full retry period, events are lost and cannot be recovered.

The following table shows the first seven retry attempts:

Retry	Delay after previous	Time since first attempt
0	1 min	1 min
1	2 min	3 min
2	5 min	8 min
3	10 min	18 min
4	17 min	35 min
5	26 min	1 h 01 min
6	37 min	1 h 38 min

Access method comparison [#access-method-comparison]

Not all situations suit webhooks. The table below compares three ways to get message event data from Infobip: webhooks, polling, and logs.

Mechanism	How it works	When to use it
Webhooks	Infobip pushes events to your endpoint in real time	Real-time processing; business logic triggered by events
Polling	You fetch batches of delivery reports on demand (last 48 hours; consumed on retrieval)	When you cannot expose a public endpoint. Each channel has its own polling endpoint (for example, for SMS: Get outbound SMS delivery reports). See your channel API reference for other channels.
Logs	You query a read-only record of message activity (last 48 hours; not consumed)	Displaying message history in the web interface. Each channel has its own logs endpoint. Example: SMS outbound logs. For other channels, see your channel API reference. See Message logs for more.

Troubleshooting

Problem	Solution
Webhook endpoint not receiving events	Verify your endpoint is publicly accessible and returns HTTP 200. Check firewall rules. Confirm the webhook URL is correctly configured in your request or subscription.
Events stopped after downtime	If your endpoint was unavailable for the full retry period, events are lost and cannot be recovered. Use Message logs to check individual message statuses for the affected period.
Cannot expose a public endpoint	Use polling instead. See the Polling row in Access method comparison.

Related pages

Metrics API
Query aggregated performance data programmatically across all channels through a single endpoint.

Message logs
Access per-message delivery status and details through the Analyze interface or Logs API.

Was this page helpful?