RCS webhooks

RCS webhooks let you receive message sending and recipient activity events without polling the API.

Contents

• Configuration
• Security headers
• Example payload
• Event types
• Duplicates and retries
• Best practices

Configuration

An account administrator configures webhooks under RCS -> Settings.

During setup:

1. Specify the destination URL that receives events
2. Select supported event types
3. Save the configuration for the RCS account

The receiving endpoint should be publicly accessible over HTTPS and able to handle repeated deliveries of the same event.

Security headers

Every webhook call contains these headers:

Header	Meaning
X-Confirmation-Event	Event type
X-Confirmation-Id	Unique event ID
X-Confirmation-Signature	sha256=<hex HMAC-SHA256> signature

The signature is calculated from the raw request body using the integration secret. Verify the signature before processing the payload.

Node.js example:

import crypto from 'node:crypto'

const rawBody = requestBodyAsString
const signature = request.headers['x-confirmation-signature'] || ''
const expected = `sha256=${crypto
  .createHmac('sha256', integrationSecret)
  .update(rawBody)
  .digest('hex')}`

if (signature !== expected) {
  throw new Error('Invalid webhook signature')
}

Warning

Use the raw request body for verification. Parsing JSON before calculating the HMAC may change the data format and invalidate signature verification.

Example payload

Example user action event:

{
  "eventId": "rcse_tY8xZb5vN0h2",
  "type": "rcs.user.action",
  "occurredAt": "2030-07-27T10:00:05.000Z",
  "data": {
    "messageId": "rcsm_01J9ZQ4ZQ9M8D2",
    "campaignId": null,
    "clientReferenceId": "order-2026-000123",
    "agentId": "google-rbm-agent-id",
    "recipient": "+48500100200",
    "action": {
      "type": "quick_reply",
      "payload": "CONFIRM",
      "text": "Confirm"
    }
  }
}

Main fields:

• eventId uniquely identifies the event
• type specifies the event type
• occurredAt contains the time the event occurred
• data.messageId identifies the RCS message
• data.campaignId identifies the campaign if the event originated from one
• data.clientReferenceId links the event to an external system
• data.agentId identifies the RCS agent
• data.recipient contains the recipient's phone number
• data.action appears for rcs.user.action and describes the action performed

Event types

Event type	Description
rcs.message.sent	Message sent to the RCS operator
rcs.message.delivered	Message delivered to the recipient
rcs.message.read	Recipient read the message
rcs.message.expired	Message expired before delivery or reading
rcs.user.message	Recipient sent a message to the agent
rcs.user.action	Recipient performed an action, such as clicking a button
rcs.user.unsubscribed	Recipient unsubscribed from communication

For rcs.user.action events, action contains details of the action, such as:

• type
• payload
• text

Duplicates and retries

The same event may be delivered more than once. The webhook receiver should operate idempotently.

• Store eventId after successfully processing an event
• Ignore duplicates with the same eventId
• Return 2xx only after storing or durably handling the event

For transport errors and 408, 429 or 5xx responses, the API makes up to three redelivery attempts.

Best practices

• Verify X-Confirmation-Signature before reading business data
• Log eventId, type, messageId and campaignId when present
• Process webhooks asynchronously if processing takes longer
• Make the endpoint resilient to duplicates and brief traffic spikes
• Respond promptly with 2xx once the event has been safely stored