RCS webhook guide

Registering an endpoint

POST /v1/webhook-endpoints takes a public HTTPS url and an events array. Private, loopback and link-local addresses are rejected, the URL may not carry embedded credentials, and redirects are followed only on the same origin. Unknown event names are dropped silently, and at least one known event is required. The response is the only time the endpoint secret is returned: store it immediately, because that secret keys every signature from then on. To rotate it, delete the endpoint and create it again.

Two more calls round out the management surface. PATCH /v1/webhook-endpoints/{id} changes the destination or the subscribed events, and it is also how you re-enable an endpoint: after 10 consecutive failed deliveries the endpoint is switched off (isActive: false) until you set isActive: true again. GET /v1/webhook-endpoints/{id}/deliveries lists every attempt, newest first, with the HTTP status your endpoint returned (or null on a timeout or network error), the attempt number and the X-Webhook-Delivery-Id of that attempt, which is the id to quote to support.

Verifying a delivery

Each delivery is an HTTPS POST with a JSON body. X-Signature is the lowercase hex HMAC-SHA256 of the raw request body, keyed with the endpoint secret. Recompute it over the raw bytes before any JSON parsing or middleware reformatting, compare with a constant-time comparison, and reject anything that does not match. An unverified webhook is a way for anyone who learns the URL to inject fake opt-outs and fake inbound messages, so the check is mandatory, not a hardening step for later.

Test deliveries use the same envelope with data: { "test": true } and whatever event name you asked for (POST /v1/webhook-endpoints/{id}/test sends one synchronously and returns the result; the portal's connectivity test uses the event name test). After the signature check, acknowledge and ignore anything with data.test === true before you route on senderIdId or contactPhone. Missing routing fields on their own never mean a test. Test deliveries are not retried and time out after 5 seconds.

The envelope and the eleven events

Every event arrives as { "event", "data", "timestamp", "orgId" }, with brandId and campaignId present only for organisations that use multi-brand scoping. The events emitted today:

The message status values are QUEUED, PROCESSING, SENT, DELIVERED, SEEN, FAILED and CANCELED. The typical sequence is QUEUED, SENT, DELIVERED, SEEN; FAILED is terminal. message.status is the delivery-receipt event: the names message.delivered, message.read and message.failed can be subscribed to but are reserved and not emitted, as are blast.completed, blast.failed, contact.created, contact.updated, contact.opted_out, session.started, session.expired, payment.succeeded and payment.failed.

Two fields deserve a note. senderIdId is the message-time SimplyRCS sender id, the same identifier you send with, and contactPhone is the other party's E.164 number at message time; either can be null when unproven, and both can be absent on older queued events or when adding them would push the body past the 256 KiB limit. Never infer a sender from their absence. And conversationId on an inbound event is the id to reply on: POST /v1/conversations/{conversationId}/messages keeps the reply in the same thread, which is what replaces polling for a gateway-style integration.

A message.received delivery for a tapped reply, with fictional values:

{
  "event": "message.received",
  "data": {
    "senderIdId": "snd_7f3a",
    "contactPhone": "+14155550142",
    "messageId": "msg_01h9",
    "conversationId": "cnv_4k2p",
    "contactId": "ct_8f21",
    "channelId": "ch_rcs_us",
    "channelType": "RCS",
    "direction": "IN",
    "contentJson": { "type": "text", "text": "Confirm" }
  },
  "timestamp": "2026-10-22T19:40:00Z",
  "orgId": "org_2b1c"
}

Snippet status: example payload built from the spec's envelope and event fields with fictional values, not a captured delivery.

A button.clicked event for the same tap arrives separately with buttonPayload: "confirm_appt_1043", so subscribe to that event when you only care about button traffic and leave contentJson parsing to the cases that need it.

Retries, duplicates and the upstream boundary

A delivery that times out or returns a non-2xx is retried up to 4 attempts in total, with exponential backoff starting at 5 seconds. Retries resend the exact same body bytes, so X-Signature is identical across every attempt of one event: use it, or a hash of the raw body, as your deduplication key. X-Webhook-Delivery-Id changes on every attempt and is for support lookups, not deduplication. Do not deduplicate on the event name plus an entity id either, because message.status legitimately fires several times for one message.

That is the whole of what the platform does on its side: sign, deliver, retry four times, log each attempt, and switch the endpoint off after ten consecutive failures. It does not queue events beyond the fourth attempt, replay them later or hold a dead-letter queue for you, so a long outage means the events of that window are gone from the stream and have to be reconciled from GET /v1/reports/messages and the conversation endpoints afterwards. Everything else is yours: a handler that validates the signature, writes the event to your own queue, returns 2xx inside a second or two, and processes asynchronously; idempotent processing keyed on the signature; sequencing on timestamp rather than arrival order, since a SEEN can arrive before the DELIVERED it follows; opt-out and consent events written to your suppression list before anything else; and a parking place for payloads that fail to parse so one malformed event cannot stall the pipeline.

Before relying on any of that in production, have an engineer run four runtime tests against a test endpoint (none has been run yet; the results belong on this page with the environment and date): send a test delivery with a wrong secret and confirm it is rejected, return a 500 and watch the four attempts land with the same signature, answer slowly and confirm the retry arrives while the first attempt is still processing, and let an endpoint fail ten times to see the auto-disable and the PATCH that revives it. The delivery log exists for exactly this.

The events and their fields are listed in RCS event types, how RCS read receipts work covers the read event, and the developer hub is where keys and callback URLs are registered.