Set up webhook notifications for messaging events

Configure webhook notifications to receive real-time updates about your messaging events including delivery confirmations, seen status, and inbound messages. This tutorial shows how to programmatically set up a complete webhook system that automatically notifies your application when important message events occur.

The tutorial focuses specifically on RCS messaging webhook events. The same principles can be adapted for other Infobip messaging channels with channel-specific modifications.

Why webhook notifications are important?

Webhook notifications enable you to track the complete lifecycle of your messages without constantly polling for status updates. You'll receive instant notifications when messages are delivered, when recipients view them, and when they respond - essential for building responsive customer communication workflows.

NOTE

To set up webhooks from within the Infobip account (opens in a new tab), check out the Create and Manage subscription documentation. To use the API, follow this tutorial.

Products and channels

Prerequisites

Infobip account. If you do not have an account, sign up (opens in a new tab) for a free trial account.
Infobip API key with the correct scope. For example, if using the RCS channel, you need the rcs:message:send scope. Learn how to create an API key with the correct scope (opens in a new tab).
HTTP client for making API requests. This tutorial uses cURL, but you can use any HTTP client or the official Infobip SDK (opens in a new tab) for your preferred programming language.
Sender configured for your account and correct channel. For example, if using the RCS channel, you need an RCS sender/agent. Contact your Account Manager to configure a custom sender if needed.
Destination phone number for testing. Note that if in free trial or testing mode, messages can only be sent to verified phone numbers.
Publicly accessible webhook endpoint URL where Infobip can send event notifications.

Process overview

Create a subscription and notification profile to define which events to track.
Configure and send a messages with webhooks enabled.
Handle incoming webhook notifications at your endpoint.

Step 1: Create the subscription and notification profile

Create a subscription (opens in a new tab) that defines which message events should trigger webhook notifications to your endpoint.

Send Create subscription endpoint

curl -X POST "https://{YOUR_BASE_URL}/webhooks/1/subscriptions/RCS" \
-H "Authorization: App {YOUR_API_KEY}" \
-H "Content-Type: application/json" \
-d '{
  "subscriptionId": "RCS Webhook",
  "name": "RCS Webhook",
  "events": [
    "DELIVERY",
    "SEEN",
    "CLICK",
    "INBOUND_MESSAGE"
  ],
  "resources": [
    "YOUR_SENDER"
  ],
  "profile": {
    "profileId": "NOTIF-RCS_DLR",
    "webhook": {
      "notifyUrl": "YOUR_WEBHOOK_URL"
    },
    "security": {
      "authId": "BASIC_ipozar",
      "type": "BASIC",
      "credentials": {
        "username": "YOUR_USERNAME",
        "password": "YOUR_PASSWORD"
      }
    }
  }
}'

{
  "subscriptionId": "RCS Webhook",
  "profile": {
    "profileId": "NOTIF-RCS_DLR",
    "security": {
      "authId": "BASIC_ipozar"
    }
  }
}

Key points:

events: Array of event types to monitor. The events change depending on the channel. See the API reference (opens in a new tab) for details.
profile: Notification profile with the webhook URL and security settings. Here, you can create a new notification profile by providing details as described in the API schema (opens in a new tab), or if you pass in the profileId the API will fetch the existing profile to use with the subscription.

A complete list of available events for each Infobip product is available in the event subscriptions documentation.

Once you receive the response, make note of the subscriptionId. You'll need it for managing the subscription later.

Step 2: Send an RCS message with webhooks enabled

Now, send a message (opens in a new tab) with a webhook option enabled to receive delivery and seen reports.

Send RCS messages endpoint

curl -X POST https://{YOUR_BASE_URL}/rcs/2/messages
-H 'Authorization: App {YOUR_API_KEY}'\
-H 'Content-Type: application/json' \
-d '{
   "messages": [
    {
      "sender": "YOUR_SENDER",
      "destinations": [
        {
          "to": "YOUR_DESTINATION"
        }
      ],
      "content": {
        "text": "This message is to show a webhook delivery and seen messages sent through the RCS channel.",
        "type": "TEXT"
      },
      "webhooks": {
        "delivery": {
          "url": "YOUR_URL",
          "intermediateReport": true,
          "notify": true
        },
        "seen": {
          "url": "YOUR_URL"
        }
      }
    }
  ]
}'

{
  "messages": [
    {
      "to": "+1234567890",
      "status": {
        "groupId": 1,
        "groupName": "PENDING",
        "id": 7,
        "name": "PENDING_ACCEPTED",
        "description": "Message sent to next instance"
      },
      "messageId": "msg_12345678-1234-5678-9012-123456789abc"
    }
  ]
}

Key points:

webhooks.delivery.notify: Set to true to receive delivery reports.
webhooks.seen.url: Provide a URL to which a seen (read receipt) report will be sent.

Step 3: Handle webhook notifications

Your webhook endpoint will receive HTTP POST requests for each configured event. Here are examples of the webhook payloads you'll receive:

DELIVERED event webhook:

{
  "results": [
    {
      "bulkId": "17608971604431585048019",
      "price": {
        "pricePerMessage": 1.000000,
        "currency": "EUR"
      },
      "status": {
        "id": 5,
        "groupId": 3,
        "groupName": "DELIVERED",
        "name": "DELIVERED_TO_HANDSET",
        "description": "Message delivered to handset",
        "action": null
      },
      "error": {
        "id": 0,
        "name": "NO_ERROR",
        "description": "No Error",
        "groupId": 0,
        "groupName": "OK",
        "permanent": false
      },
      "messageId": "17608971604431585048020",
      "doneAt": "2025-10-18T13:52:42.878+0000",
      "messageCount": 1,
      "sentAt": "2025-10-18T13:52:42.878+0000",
      "to": "447415774332",
      "sender": "ibpDemoPly",
      "platform": {
        "entityId": null,
        "applicationId": null
      }
    }
  ]
}

SEEN event webhook:

{
  "results": [
    {
      "messageId": "17608971604431585048020",
      "from": "ibpDemoPly",
      "to": "447415774332",
      "sentAt": "2025-10-18T13:52:42.878+0000",
      "seenAt": "2025-10-18T13:52:42.878+0000"
    }
  ]
}

INBOUND_MESSAGE event webhook:

{
  "results": [
    {
      "sender": "447415774332",
      "to": "ibpDemoPly",
      "integrationType": "RCS",
      "receivedAt": "2025-10-18T13:52:42.878+0000",
      "messageId": "MxrzgtEdmRtW0g8eQ0diqGA",
      "pairedMessageId": "17608971604431585048020",
      "callbackData": null,
      "message": {
        "type": "text",
        "text": "Hello"
      },
      "price": {
        "pricePerMessage": 1.000000,
        "currency": "EUR"
      },
      "messageCount": 1,
      "pendingMessageCount": 656
    }
  ]
}

TIP

Use tools like ngrok to create a publicly accessible URL for local testing, or webhook testing services like webhook.site to inspect incoming webhook payloads during development.

Implementation outcome

After successful implementation, your system will automatically receive real-time notifications for:

Message delivery confirmations with delivery timestamps and status details
Read receipts showing when recipients view your messages
Inbound message notifications with full message content and sender information
Detailed pricing information for delivered messages
Error notifications if message delivery fails