About Webhooks

Kudosity’s Webhooks API enables you to subscribe to key messaging events in real time. To receive events, you must configure a publicly accessible HTTPS endpoint that can accept POST requests. Each event includes an event_type field to indicate the kind of event and also include a status object with more detailed delivery information.

Supported `event_type` Values

Event Type	Description
`LINK_HIT`	Triggered when a tracked link in a message is clicked
`OPT_OUT`	Triggered when a recipient opts out via link or STOP reply
`MMS_INBOUND`	Triggered when an inbound MMS is received
`MMS_STATUS`	Delivery status updates for MMS messages
`SMS_INBOUND`	Triggered when an inbound SMS is received
`SMS_STATUS`	Delivery status updates for SMS messages
`RCS_STATUS`	Delivery status updates for RCS messages (includes extra RCS-specific info)
`RCS_INBOUND`	Triggered when an inbound RCS message is received (supports rich content)
`WHATSAPP_STATUS`	Delivery status updates for WhatsApp messages (submitted, delivered, read, failed, etc.)
`WHATSAPP_INBOUND`	Triggered when an inbound WhatsApp message is received (supports rich content)

⚠️ Important: `event_type` Field Deprecation

The event_type field is deprecated and will be removed in a future version. All new webhook implementations should use the filter.event_type array instead.

Timeline: Existing webhooks using event_type will continue to work, but we recommend migrating to the new filter-based approach as soon as possible.

Migration Example

// ❌ Old approach (deprecated)
{
  "event_type": "SMS_STATUS",
  "name": "SMS Status Webhook",
  "url": "https://example.com/webhook"
}

// ✅ New approach (recommended)
{
  "filter": {
    "event_type": ["SMS_STATUS"]
  },
  "name": "SMS Status Webhook",
  "url": "https://example.com/webhook"
}

Status Events

For all status-related events (MMS_STATUS, SMS_STATUS, RCS_STATUS), the payload includes a status object that contains metadata about the message and its delivery state.

Common Status Values

These values apply to both SMS and MMS messages:

SENT: Message has been submitted to the carrier.
DELIVERED: Message has been delivered to the recipient's handset.
FAILED: Message failed due to an error from the carrier or device.
ACCEPTED: Message was accepted by the carrier; delivery may have been attempted.
SOFT_BOUNCE: Message was undeliverable due to a temporary issue (e.g., handset off or out of range).
HARD_BOUNCE: Message failed due to a permanent issue (e.g., number disconnected).
REJECTED: Message was rejected by Kudosity (e.g., due to compliance validation).
OTHER: A status that does not match any known enum; provided as-is from the carrier.

RCS Status Events

The RCS_STATUS event is triggered when the status of an RCS message changes. These updates are sent as a webhook with a status object that includes delivery metadata and a status field indicating the message’s current state.

Supported RCS Status Values

Status	Description
`SENT`	The message has been submitted to the carrier for delivery.
`DELIVERED`	The message has been delivered to the recipient’s device.
`FAILED`	Delivery failed due to a carrier or handset error.
`READ`	The message was read by the recipient (when supported by device/carrier).
`REJECTED`	The carrier or gateway rejected the message (for example, a non-RCS-capable handset).
`UNDELIVERABLE`	The message reached the carrier but couldn’t be delivered (handset unreachable or expired).
`OTHER`	A status that doesn’t map to a known value; passed through as-is from the carrier.

📘
Polling vs. webhooks
The GET /v2/rcs/messages and GET /v2/rcs/messages/{id} endpoints collapse REJECTED, UNDELIVERABLE, and expiry into FAILED. A message that reads FAILED when polled may have reported the more specific REJECTED or UNDELIVERABLE over the webhook.

WhatsApp Status Events

The WHATSAPP_STATUS event is triggered when the status of a WhatsApp message changes.

Supported WhatsApp Status Values:

SUBMITTED - Message submitted to provider
DELIVERED - Delivered to recipient
READ - Message read by recipient
REJECTED - Message rejected
UNDELIVERABLE - Message undeliverable
FAILED - Failed delivery

Enhanced Filtering Capabilities

The new filter object provides powerful filtering beyond the legacy event_type field:

Multiple Event Types

Subscribe to multiple event types in one webhook:

{
  "filter": {
    "event_type": ["SMS_STATUS", "SMS_INBOUND", "OPT_OUT"]
  },
  "name": "Multi-Event Webhook",
  "url": "https://example.com/webhook"
}

Advanced Filtering

Filter by sender, status, message reference, and campaign:

{
  "filter": {
    "event_type": ["SMS_STATUS"],
    "sender": ["+61412345678", "+61487654321"],
    "status": ["DELIVERED", "FAILED"],
    "campaign_id": ["summer-sale"]
  },
  "name": "Filtered SMS Webhook",
  "url": "https://example.com/webhook"
}

Filter Logic

Within each filter array: OR logic (matches any value)
Between different filters: AND logic (must match all conditions)

Available Filter Fields

event_type: Array of event types to subscribe to (replaces the deprecated single event_type field)
sender: Array of sender addresses to filter by
message_ref: Array of message references to filter by
status: Array of message statuses to filter by (applies to status events only)
campaign_id: Array of campaign IDs to filter by

Link Hit

The LINK_HIT event is triggered any time a recipient visits a link that is tracked. Track Links is an optional flag on the send message API calls. Along with the URL that was being tracked is a hits field indicating how many visits this tracked link has in total and a source_message which contains the track link sent to the recipient.

Example Payloads

{
  "event_type": "LINK_HIT",
  "timestamp": "2021-05-06T05:19:42.123456Z",
  "webhook_id": "fd0e6485-b905-44c1-bd55-fee1d0d6d864",
  "webhook_name": "Link Tracking Webhook",
  "link_hit": {
    "hits": 1,
    "url": "https://www.example.com/abc",
    "source_message": {
      "type": "MMS",
      "id": "b50e4dc1-e57f-459c-a15c-526bee00a4c4",
      "message": "Hey, Check this out! http://clckme.info/KYhSsuIH Opt-out reply STOP",
      "message_ref": "D701",
      "recipient": "61435790000",
      "sender": "61481074191",
      "subject": "Hello",
      "content_urls": [
        "https://res.cloudinary.com/burstsms/image/upload/v1618798563/284KB_qgqtbe.jpg"
      ]
    }
  }
}

{
  "event_type": "LINK_HIT",
  "timestamp": "2021-07-20T23:14:04.789012Z",
  "webhook_id": "fd0e6485-b905-44c1-bd55-fee1d0d6d864",
  "webhook_name": "Link Tracking Webhook",
  "link_hit": {
    "hits": 1,
    "url": "https://www.example.com/abc",
    "source_message": {
      "type": "SMS",
      "id": "faf68308-16cd-4cf9-aef7-47342bd405be",
      "message": "Hey, Check this out! http://clckme.info/KYhSsuIH for Opt-out reply STOP or hit opt out link - http://nsub.me/vqHTcCsh",
      "message_ref": "D301",
      "recipient": "61435795809",
      "sender": "61481074185"
    }
  }
}

Opt Out

The OPT_OUT event is triggered when a recipient has visited an opt-out link in a message they have received or by sending a message with the text "STOP".

Using parameter [opt-out-link] in message body, inserts the opt-out link.

The source field will be set according to the method a recipient has used to opt-out and contain a value of either link or SMS.

Example Payloads

{
  "event_type": "OPT_OUT",
  "timestamp": "2021-05-06T05:16:20.456789Z",
  "webhook_id": "fd0e6485-b905-44c1-bd55-fee1d0d6d864",
  "webhook_name": "Opt Out Webhook",
  "opt_out": {
    "source": "LINK_HIT",
    "source_message": {
      "type": "SMS",
      "id": "a51ebe4e-a412-440e-a8d9-464e68a521cc",
      "message": "Hey, Check this out! http://clckme.info/KYhSsuIH for Opt-out reply STOP or hit opt out link - http://nsub.me/vqHTcCsh",
      "message_ref": "ncc5009d",
      "recipient": "61435790000",
      "sender": "61481074190"
    }
  }
}

{
  "event_type": "OPT_OUT",
  "timestamp": "2021-05-06T05:16:20.654321Z",
  "webhook_id": "fd0e6485-b905-44c1-bd55-fee1d0d6d864",
  "webhook_name": "Opt Out Webhook",
  "opt_out": {
    "source": "SMS_INBOUND",
    "source_message": {
      "type": "SMS",
      "id": "a51ebe4e-a412-440e-a8d9-464e68a521cc",
      "message": "Hey, Check this out! http://clckme.info/KYhSsuIH for Opt-out reply STOP or hit opt out link - http://nsub.me/vqHTcCsh",
      "message_ref": "ncc5009d",
      "recipient": "61435790000",
      "sender": "61481074190"
    }
  }
}

MMS Inbound

The MMS_INBOUND event is posted to you on receipt of an MMS sent from a recipient to one of the senders listed on your account. For convenience we will try and find a message that you have sent to this recipient from that sender in the past 72 hours and supply it as the last_message field. This is useful for determining if an inbound message is potentially a reply.

{
  "event_type": "MMS_INBOUND",
  "timestamp": "2021-05-06T05:16:33.987654Z",
  "webhook_id": "fd0e6485-b905-44c1-bd55-fee1d0d6d864",
  "webhook_name": "MMS Inbound Webhook",
  "mo": {
    "type": "MMS",
    "id": "alss-2way-605b31c7-d2c49104",
    "sender": "61435790000",
    "recipient": "61481074190",
    "message": "Here's a cute picture",
    "media": [
      {
        "name": "image-0.png",
        "content": "BASE64-encoded-string------"
      }
    ],
    "last_message": {
      "type": "SMS",
      "id": "a51ebe4e-a412-440e-a8d9-464e68a521cc",
      "message": "Hey, check this out!",
      "message_ref": "ncc5009d",
      "recipient": "61435790000",
      "sender": "61481074190"
    }
  }
}

MMS Status

The MMS_STATUS event data is posted to you for changes to an MMS message status. These are currently only comprised of internal statuses (SENT, FAILED).

{
  "event_type": "MMS_STATUS",
  "timestamp": "2021-05-06T05:19:33.234567Z",
  "webhook_id": "fd0e6485-b905-44c1-bd55-fee1d0d6d864",
  "webhook_name": "MMS Status Webhook",
  "status": {
    "type": "MMS",
    "id": "b50e4dc1-e57f-459c-a15c-526bee00a4c4",
    "message_ref": "D7001",
    "recipient": "61435790000",
    "sender": "61481074191",
    "status": "SENT"
  }
}

SMS Inbound

The SMS_INBOUND event is posted to you on receipt of an SMS sent from a recipient to one of the senders listed on your account. For convenience we will try and find a message that you have sent to this recipient from that sender and supply it as the last_message field. This is useful for determining if an inbound message is potentially a reply. The routed_via field will display when a shared local number has been used to deliver your message.

{
  "event_type": "SMS_INBOUND",
  "timestamp": "2021-05-06T05:16:33.345678Z",
  "webhook_id": "fd0e6485-b905-44c1-bd55-fee1d0d6d864",
  "webhook_name": "SMS Inbound Webhook",
  "mo": {
    "type": "SMS",
    "id": "alss-2way-605b31c7-d2c49104",
    "message": "Stop",
    "recipient": "61481074190",
    "routed_via": "447507333300",
    "sender": "447507222200",
    "last_message": {
      "type": "SMS",
      "id": "a51ebe4e-a412-440e-a8d9-464e68a521cc",
      "message": "Hey, check this out!",
      "message_ref": "ncc5009d",
      "recipient": "447507222200",
      "routed_via": "447507333300",
      "sender": "61481074190"
    }
  }
}

SMS Status

The SMS_STATUS event data is posted to you for changes to a SMS message status. Multiple status events can be triggered for a single message. The routed_via field will display when a shared local number has been used to deliver your message.

SMS_Status: SENT

{
  "event_type": "SMS_STATUS",
  "timestamp": "2025-04-23T00:05:18.123456Z",
  "webhook_id": "fd0e6485-b905-44c1-bd55-fee1d0d6d864",
  "webhook_name": "SMS Status Webhook",
  "status": {
    "id": "e48d3e71-264e-4afb-9c06-edec1f0bb9d4",
    "type": "SMS",
    "message_ref": "test V2 QA SMS Send",
    "sender": "447507222200",
    "routed_via": "6140000000",
    "recipient": "6140000000",
    "status": "SENT"
  }
}

SMS_Status: DELIVERED

{
  "event_type": "SMS_STATUS",
  "timestamp": "2025-04-23T00:05:18.567890Z",
  "webhook_id": "fd0e6485-b905-44c1-bd55-fee1d0d6d864",
  "webhook_name": "SMS Status Webhook",
  "status": {
    "id": "e48d3e71-264e-4afb-9c06-edec1f0bb9d4",
    "type": "SMS",
    "message_ref": "test V2 QA SMS Send",
    "sender": "447507222200",
    "routed_via": "6140000000",
    "recipient": "6140000000",
    "status": "DELIVERED"
  }
}

RCS Status

Example Payloads

{
  "event_type": "RCS_STATUS",
  "timestamp": "2025-07-01T09:32:10.876543Z",
  "webhook_id": "fd0e6485-b905-44c1-bd55-fee1d0d6d864",
  "webhook_name": "RCS Status Webhook",
  "status": {
    "type": "RCS",
    "id": "bc2e0a4a-7e21-49de-9912-20cb4148c21f",
    "message_ref": "promo-campaign-001",
    "sender": "DemoAgent",
    "recipient": "61400000000",
    "status": "READ"
  }
}

RCS Inbound

The RCS_INBOUND event is posted to you when a recipient replies in an RCS conversation. This includes free-text replies, which are not opt-out keywords, taps on a suggested reply or action, and rich replies such as images and shared locations. The reply is delivered as a mobile-originated (mo) message.

The mo.sender field is the recipient who sent the reply, and the mo.recipient field is the RCS agent that received it. The mo.content_type field identifies the type of reply, and the matching content is nested under mo.content. Supported RCS content types are TEXT, SUGGESTION, IMAGE, VIDEO, AUDIO, FILE, LOCATION, and CONTACT.

Example Payloads

{
  "event_type": "RCS_INBOUND",
  "timestamp": "2025-07-01T09:34:51.246802Z",
  "webhook_id": "fd0e6485-b905-44c1-bd55-fee1d0d6d864",
  "webhook_name": "RCS Inbound Webhook",
  "mo": {
    "type": "RCS",
    "id": "bc2e0a4a-7e21-49de-9912-20cb4148c21f",
    "sender": "61400000000",
    "recipient": "DemoAgent",
    "content_type": "TEXT",
    "content": {
      "text": {
        "message": "Yes, that time works for me."
      }
    }
  }
}

A SUGGESTION event is sent when the recipient taps a suggested reply or action on a message you sent. The label of the suggestion is in mo.content.suggestion.text, and the postback_data value for the suggestion is in mo.content.suggestion.postback_data. See Handle a tap in your application.

{
  "event_type": "RCS_INBOUND",
  "timestamp": "2025-07-01T09:35:20.246802Z",
  "webhook_id": "fd0e6485-b905-44c1-bd55-fee1d0d6d864",
  "webhook_name": "RCS Inbound Webhook",
  "mo": {
    "type": "RCS",
    "id": "5d1c7a90-3f6e-4b0a-8f27-91c4e2a6b7d3",
    "sender": "61400000000",
    "recipient": "DemoAgent",
    "content_type": "SUGGESTION",
    "content": {
      "suggestion": {
        "text": "Yes",
        "postback_data": "appt-789-yes"
      }
    }
  }
}

WhatsApp Status

Example Payloads

WhatsApp Read Event

{
  "event_type": "WHATSAPP_STATUS",
  "status": {
    "id": "9a372bac-8c39-4ce3-bde1-f8f7562c6933",
    "message_ref": "payment-reminder-ref-002",
    "recipient": "61411111111",
    "sender": "61411111111",
    "status": "READ",
    "type": "WHATSAPP"
  },
  "timestamp": "2025-12-16T08:01:02Z",
  "webhook_id": "d68f7766-ed51-443e-852f-8a0c7655b7f4",
  "webhook_name": "WhatsApp All Events Webhook"
}

WhatsApp Delivered Event

{
  "event_type": "WHATSAPP_STATUS",
  "status": {
    "id": "9a372bac-8c39-4ce3-bde1-f8f7562c6933",
    "message_ref": "payment-reminder-ref-002",
    "recipient": "61411111111",
    "sender": "61411111111",
    "status": "DELIVERED",
    "type": "WHATSAPP"
  },
  "timestamp": "2025-12-16T08:00:48Z",
  "webhook_id": "d68f7766-ed51-443e-852f-8a0c7655b7f4",
  "webhook_name": "WhatsApp All Events Webhook"
}

WhatsApp Inbound Event

{
  "event_type": "WHATSAPP_INBOUND",
  "mo": {
    "content": {
      "reaction": {
        "action": "react",
        "emoji": "❤️"
      }
    },
    "content_type": "REACTION",
    "id": "552e8cfc-5d5a-4b13-9523-c4bbce93c5c0",
    "recipient": "61411111111",
    "sender": "61411111111",
    "type": "WHATSAPP"
  },
  "timestamp": "2025-12-16T08:24:33Z",
  "webhook_id": "d68f7766-ed51-443e-852f-8a0c7655b7f4",
  "webhook_name": "WhatsApp All Events Webhook"
}

Supported event_type Values

⚠️ Important: event_type Field Deprecation

Migration Example

Status Events

Common Status Values

RCS Status Events

Polling vs. webhooks

WhatsApp Status Events

Enhanced Filtering Capabilities

Multiple Event Types

Advanced Filtering

Filter Logic

Available Filter Fields

Link Hit

Opt Out

MMS Inbound

MMS Status

SMS Inbound

SMS Status

RCS Status

RCS Inbound

WhatsApp Status

WhatsApp Read Event

WhatsApp Delivered Event

WhatsApp Inbound Event

Supported `event_type` Values

⚠️ Important: `event_type` Field Deprecation