Webhooks
Webhooks let you receive event notifications in real time across messaging channels and platform services. Infobip sends a POST request to your endpoint the moment an event occurs, covering delivery status, clicks, read receipts, inbound messages, and more. This removes the need to poll for updates. Webhooks do not store data. Events are pushed in real time and not retained by Infobip.
Use webhooks when you need real-time event processing, want to store data in your own systems, or are building a multitenant platform. When you only need analytics or scheduled exports, the built-in reporting tools require less configuration.
Supported channels and services
Webhooks support messaging channels such as SMS, Email, WhatsApp, and RCS, and platform services such as Mobile Identity, Number Lookup, and Blocklist. For the complete list of channels, services, and event types, see Available webhook events.
Who can use webhooks
Webhooks are available to all accounts. To manage webhook subscriptions in the web interface, you need the Account admin or Channel setup and integrations role. To manage them through the Subscriptions API, the API key needs the subscriptions:manage scope.
Configuration methods
You can configure webhooks in four ways:
| Method | Description | Best for |
|---|---|---|
| Per-request | Specify the webhook URL when sending each message. APIs with the webhooks.delivery object use url, contentType, and notify. APIs using the legacy parameter style use notifyUrl and notifyContentType. See the send API reference for your channel for the exact parameters. | Message-level control. Different endpoints per message. |
| Account-level default | Contact Support to configure a single default webhook URL for your account. It receives delivery reports for all channels, with no filtering. Other events, such as inbound messages and clicks, need a webhook subscription. | Delivery reports to a single endpoint, with no channel filtering |
| Webhook subscriptions | Configure channel-level subscriptions in the web interface or through the Subscriptions API. Set your endpoint URL, authentication settings, and event filters per channel. | Scalable setups requiring filtering, security, or separate endpoints per channel |
| Number-level inbound configuration | For inbound messages only. Set a forwarding action on a number or other resource, in Inbound configuration on the number details page (Channels and numbers > Numbers > My numbers), or with the Manage inbound configuration API endpoint. Forward to HTTP sends inbound messages to your URL. Apply Subscriptions sends them to your webhook subscriptions. Keywords can route specific messages to a different action. | Inbound messages routed per number or keyword |
If no webhook is specified in the request and notify is set to true or not defined, your webhook subscription settings apply. This fallback applies across all channels. A webhook URL in the request overrides your webhook subscriptions for that message. To receive no delivery report for a message, set notify to false.
For inbound messages, a forwarding action set on the number or resource takes precedence. When no forwarding action is set, your webhook subscriptions apply. To manage inbound webhooks in one place, with authentication settings, use Apply Subscriptions rather than Forward to HTTP. For the full setup guide, including notification profiles, authentication settings, and available events per channel, see the Webhook subscriptions documentation.
Choose between per-request webhooks and webhook subscriptions [#choose-between-per-request-webhooks-and-webhook-subscriptions-configuration-methods]
The following table compares the two approaches.
| Aspect | Per-request webhooks | Webhook subscriptions |
|---|---|---|
| Configuration | Specify URL in each API request | Configure once in the web interface or through the Subscriptions API |
| Scope | Message-level control | Channel-level rules |
| Maintenance | More code. Configure per message. | Centralized, easier to manage |
| Multiple endpoints | Different URL per message | Through filters and separate webhook subscriptions |
| Filtering | None at webhook level | By application, entity, user, resource, and keyword (inbound messages) |
| Security | HTTPS. Authentication settings and mTLS through a standalone notification profile that matches the URL. | Authentication settings (Basic, HMAC, OAuth) and mTLS |
Webhook event types
Webhook payloads differ by event type and channel. Each event type has its own schema in the channel API reference. The following table lists the event types:
| Event type | What triggers it | Availability |
|---|---|---|
DELIVERY | Message reaches a final status (delivered, failed, expired, rejected). Includes status, error codes, timing, and fields from your original request. For which statuses are final and which are intermediate, see Message delivery lifecycle. | All supported messaging channels |
INBOUND_MESSAGE | A subscriber sends a message to a number or address you own. Includes sender, content, and timestamp. | Channels that support two-way messaging |
CLICK | A recipient clicks a shortened URL in your message. Requires URL shortening and tracking to be enabled. | Channels that support URL tracking |
SEEN | A recipient views your message (read receipt). | Channels that support read receipts, for example WhatsApp, RCS, and Viber. See Available webhook events. |
| Platform service results (category, not a single event) | An asynchronous service request completes (Mobile Identity verification, Number Lookup, Blocklist change). Schemas vary by service. | Mobile Identity, Number Lookup, Blocklist |
One webhook request can contain more than one event. For example, an SMS delivery report request contains up to 100 reports by default. To change the batch size, set it in the notification profile, or with maxBucketSize in the Subscriptions API.
Common fields across delivery webhooks [#common-fields-across-delivery-webhooks-webhook-event-types]
The following fields appear across most delivery webhook payloads. Full schemas are in the API reference. To act on the status and error objects in a delivery report, including when to resend a failed message, see Handling errors.
| Field | Description | SMS API v3 and most channels | SMS API v2 and WhatsApp API v1 |
|---|---|---|---|
messageId | Unique message identifier for matching and tracking | Always present. Returns your custom value if set, or an Infobip auto-generated ID if omitted. | Always present. Returns your custom value if set, or an Infobip auto-generated ID if omitted. |
bulkId | Bulk identifier for grouped messages or multiple recipients | Auto-generated. Always present. Not customizable. | Your value appears if set. Absent if not set. |
callbackData | Custom data: order IDs, references, or any metadata. Up to 4,000 characters in most send APIs. See your channel API reference for the limit. | Present if set. Absent if omitted. | Present if set. Absent if omitted. |
campaignReferenceId | Campaign tracking ID for analytics and organization | Present if set. Absent if omitted. | Present if set. Absent if omitted. |
entityId and applicationId | Multitenant entity and application identifiers | platform object always present (null if values not set) | platform object omitted entirely if not set in the request |
Verify webhook authenticity
Webhook subscriptions support attaching authentication settings so your endpoint can verify that an incoming request genuinely came from Infobip. Configure them through the Manage authentication settings documentation, or programmatically through Create security settings. The following methods are available:
- HMAC: A keyed hash that proves the request was signed with a shared secret. Infobip signs the request using a secret key with one of
HMAC_MD5,HMAC_SHA_1,HMAC_SHA_224,HMAC_SHA_256,HMAC_SHA_384, orHMAC_SHA_512. The signature is in theX-Hub-Signatureheader by default. To verify it, compute the hash of the raw request body, exactly as received, with the same key and algorithm. Then compare it with the header value. - Basic: The request includes HTTP Basic credentials you define.
- OAuth: The request includes an access token that Infobip gets from your token URL, using the grant type and credentials you define.
- mTLS: Mutual TLS at the connection level, set with a certificate on the notification profile. Combine it with any of the methods above. See Manage certificates.
webhooks.delivery.url or notifyUrl) use standalone notification profiles. If a standalone profile has the same URL, Infobip applies its authentication settings and certificate. Otherwise, Infobip uses the NULL profile (a standalone profile without a URL), if one exists, or sends the event without additional settings. To verify per-request webhooks, create a standalone notification profile for the URL.Push retry cycle
If your endpoint is unavailable, Infobip retries using the following formula:
Retries are numbered from 0, so retryNumber is 0 for the first retry. Infobip retries a maximum of 20 times. The last retry occurs approximately 41 hours 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 retries:
| Retry | Delay after previous attempt | 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 |
Webhooks compared with other access methods
The following table compares webhooks with 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. See the API reference for your channel. |
| Logs | You query a read-only record of message activity (last 48 hours, not consumed) | Looking up what happened to specific messages, for example for support or audits. Each channel has its own logs endpoint. See the API reference for your channel. |
Troubleshooting
The following are common issues and how to resolve them:
- My webhook endpoint is not receiving events: Verify your endpoint is publicly accessible and returns HTTP
200. Check firewall rules that may block incoming requests. Confirm the webhook URL is correctly configured in your request or webhook subscription. - Events stopped arriving after a period of downtime: The retry period lasts up to approximately 41 hours 30 minutes. If your endpoint was unavailable for the full period, events are lost and cannot be recovered. Use Message logs to look up individual message statuses for the affected period.
- I cannot expose a public endpoint: Use polling instead. See the Polling row in Webhooks compared with other access methods.
Set up webhook notifications for messaging events
Step-by-step tutorial for delivery, seen, and inbound message webhooks.
Manage notification profiles
Set the webhook URL, authentication, certificate, and delivery settings such as batch size.
Inbound messages: subscription routing
How inbound configuration on a number and webhook subscriptions work together.
Was this page helpful?