# 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](https://www.infobip.com/docs/cpaas-x). When you only need analytics or scheduled exports, the [built-in reporting tools](https://www.infobip.com/docs/reporting) 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](https://www.infobip.com/docs/subscriptions/available-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](https://www.infobip.com/docs/api/platform/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 | ContactSupportto 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 theSubscriptions 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 theManage inbound configurationAPI 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](https://www.infobip.com/docs/subscriptions). ### 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](https://www.infobip.com/docs/developer-resources/api-fundamentals/message-status-codes#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](https://www.infobip.com/docs/subscriptions/available-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](https://www.infobip.com/docs/developer-resources/api-fundamentals/handling-errors#network-and-delivery-error-codes). | 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](https://www.infobip.com/docs/subscriptions/manage/authentication-settings) documentation, or programmatically through [Create security settings](https://www.infobip.com/docs/api/platform/subscriptions-api/security/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`, or `HMAC_SHA_512`. The signature is in the `X-Hub-Signature` header 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](https://www.infobip.com/docs/subscriptions/manage/certificates). NOTE Per-request webhooks (a webhook URL in the send request, such as `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: ```text 1 min + (1 min * retryNumber^2) ``` 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](https://www.infobip.com/docs/reporting/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](#webhooks-compared-with-other-access-methods). ___ Related pages [Set up webhook notifications for messaging events](https://www.infobip.com/docs/tutorials/set-up-webhook-notifications-for-messaging-events) Step-by-step tutorial for delivery, seen, and inbound message webhooks. [Manage notification profiles](https://www.infobip.com/docs/subscriptions/manage/notification-profiles) Set the webhook URL, authentication, certificate, and delivery settings such as batch size. [Inbound messages: subscription routing](https://www.infobip.com/docs/subscriptions/inbound-messages-subscription-routing) How inbound configuration on a number and webhook subscriptions work together.