Webhooks

Webhooks let you receive real-time notifications about events like message delivery statuses or incoming messages. Instead of polling our servers, you can configure a webhook endpoint to receive updates via HTTP POST requests in JSON format.

There are two ways to receive real-time delivery reports for your messages:

• configuring a webhook object inline with each message request
• setting up persistent subscriptions through the Subscription Management API

Key difference: Per-message webhooks give you flexibility and control at the individual message level, while subscriptions reduce repetition and centralize configuration when your reporting needs are consistent across messages.

Why choose per-message webhooks

Include a webhooks object directly in your send request to configure delivery reporting for that specific message or batch. Reports are sent to your specified callback URL as message statuses change.

Best suited for:

• Ad-hoc messaging where notification requirements vary per message
• Testing and development workflows
• Scenarios where different messages need reports delivered to different endpoints
• Quick integrations without upfront configuration
• One-off campaigns with unique reporting needs

For more information, see: Webhook object.

Why choose Subscription Management API

Create persistent subscriptions that define which events trigger notifications and where they're sent. Once configured, all matching messages automatically use the subscription settings without the need for a per-message configuration.

Best suited for:

• Production environments with consistent notification requirements
• Multi-channel setups where you want unified event handling
• Scenarios requiring granular event filtering (delivery, seen, clicks, inbound messages)
• Teams managing multiple senders or applications with centralized reporting
• Long-running integrations where you want to decouple notification config from send logic

For more information, see: Subscription Management.

Webhook object

Use the webhook object to forward Delivery Reports, message status, pricing information, or GSM errors (for example, EC_ABSENT_SUBSCRIBER) to your callback server using a predefined URL. It forwards the data as soon as the Infobip platform receives it.

Key capabilities:

• Delivery reporting: Specify a callback URL to receive delivery reports (DLRs) as soon as message status changes. If your endpoint is temporarily unavailable, the platform automatically retries delivery using exponential backoff.
• Real-time intermediate reports: Receive detailed status updates as messages progress through delivery, including GSM error codes, pricing information, and network details. These reports need to be specifically requested and set up and are not always supported by all channels - contact your Account Manager or support for details about your specific use case.
• Flexible notification control: Choose whether to receive delivery reports at all. When disabled, no reports are sent. When no webhook URL is specified, your account's default subscription settings apply.
• Custom callback data: Attach custom identifiers or metadata to messages, which are automatically included in the delivery reports for easy correlation with your internal systems.
• Response format selection: Choose to receive reports in either JSON or XML format based on your integration needs.

Where to configure it

The webhooks object is nested within each message in the messages array. To use it, include a webhooks object directly in your send request. For schema, see any messaging API, for instance: SMS API.

Push Retry Cycle

If your URL is unavailable for any reason, forward attempts are made according to the following formula:

Examples for first few retry attempts are shown in the following table. The maximum number of retries is 20, that is, the last retry will occur 41:30h after the initial one. If your URL is not available for the whole retry period, the data will be lost.