Manage event formats

Format selection defines the JSON payload structure of events delivered to your webhook. Each subscription automatically uses a default format for its channel, but you can select a different format if your webhook receiver requires a specific API version or structure.

Prerequisites [#prerequisites]

To manage event formats, you need:

• Infobip account: An active account.
• Webhook subscription: At least one subscription configured. See Manage webhook subscriptions.
• Channel awareness: Knowledge of which channels your subscription monitors (default formats vary by channel).

Format selection overview [#format-selection-overview]

Each subscription automatically receives a default format (event schema), which is channel-specific to ensure consistent processing of events. If the default format does not meet your requirements, you can select a different supported format for available channels.

This allows you to:

• Control the JSON payload structure delivered to your webhook
• Use formats that match a specific API version your webhook expects
• Receive payloads that automatically adapt to the API version you used to send the original message
• Ensure compatibility with your webhook receiver logic

Default formats by channel [#default-formats]

Selectable formats [#selectable-formats]

Formats fall into two types:

• Static formats deliver a fixed payload structure tied to a specific API version (for example, delivery.sms.v3.json). All events use the same schema regardless of how the original message was sent.
• Adaptive format (adaptive.subscription.format) dynamically matches the payload to the API version the sender used to submit the original message.

Selectable formats are available for the following channels and services:

Messaging channels

Apple Messages for Business, Facebook Messenger, MMS, SMS, Open Channel

Platform services

Mobile Identity services, Blocklist tool events

For other channels, the default format is applied automatically. To change the format for other channels, contact Infobip Support.

SMS format example [#sms-formats]

SMS demonstrates all available format options. Other channels follow similar patterns.

For other channels and platform services, see Available webhook events for the complete list of events.

Select a format [#select-format]

You can select a different format when creating or editing a subscription.

When to use each format type [#when-to-use]

Use static formats when

Your webhook receiver expects a specific API version structure, you want predictable and unchanging JSON payloads, you are migrating from a specific API version and need backward compatibility, or you want consistency across all events of that type.

Use adaptive format when

You support multiple API versions in your webhook receiver, you want payloads to match the API version each sender used, you need flexibility as senders update their API versions, or your webhook can handle variable JSON structures.