Kudosity Webhooks

Create & Manage Webhooks

Webhooks allow users to receive HTTP POST notifications when events occur, such as SMS delivery status changes, inbound messages, link clicks, and opt-outs.

Authentication

• Header: x-api-key: {KUDOSITY_API_KEY}
• Credentials come from the Kudosity dashboard under Developers → API Settings

API Details

• Base URL: https://api.transmitmessage.com
• Content-Type: application/json
• All requests use curl commands

Create a Webhook

Endpoint: POST /v2/webhook

Required parameters:

• name (string): Webhook name, 2-100 characters
• url (string): HTTPS URL that accepts JSON-encoded POST requests

Optional parameters:

• filter (object): Filter which events trigger the webhook
  • event_type (array): Types of events to subscribe to
  • sender (array): Filter by sender number
  • status (array): Filter by message status (for status events only)
  • message_ref (array): Filter by message reference
  • campaign_id (array): Filter by campaign ID
• rate_limit (integer): Max requests per second to your URL (max 10,000, 0 = system default)

Available Event Types

Ten event types, covering every channel — not just SMS:

If you are sending WhatsApp or RCS, these are the event types you want — SMS_STATUS will not report on them.

Status Values

For any status event, the nested status.status field carries one of:

ACCEPTED is not DELIVERED. Treating it as a successful delivery is a common source of over-reported success rates.

Filter Logic

• Within a filter array (e.g., multiple senders): conditions are combined with OR
• Between different filters (e.g., sender AND status): conditions are combined with AND

The same filter name reads a different part of the payload depending on the event type:

The inbound row is the one that surprises people: filtering inbound events by sender filters by your number, not the customer's.

Example: Create a webhook for SMS delivery status and inbound messages

curl -s -X POST "https://api.transmitmessage.com/v2/webhook" \
  -H "x-api-key: ${KUDOSITY_API_KEY}" \
  -H "User-Agent: kudosity-skills/0.2.1" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "SMS Events",
    "url": "https://myapp.com/webhooks/sms",
    "filter": {"event_type": ["SMS_STATUS", "SMS_INBOUND"]}
  }'

Example: Create a webhook filtered to specific statuses

curl -s -X POST "https://api.transmitmessage.com/v2/webhook" \
  -H "x-api-key: ${KUDOSITY_API_KEY}" \
  -H "User-Agent: kudosity-skills/0.2.1" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Failed SMS Alerts",
    "url": "https://myapp.com/webhooks/failures",
    "filter": {"event_type": ["SMS_STATUS"], "status": ["FAILED", "HARD_BOUNCE"]}
  }'

List All Webhooks

Endpoint: GET /v2/webhook

curl -s "https://api.transmitmessage.com/v2/webhook" \
  -H "x-api-key: ${KUDOSITY_API_KEY}" \
  -H "User-Agent: kudosity-skills/0.2.1"

Webhook Payload Examples

SMS Status Event

{
  "event_type": "SMS_STATUS",
  "timestamp": "2021-05-06T05:16:07Z",
  "status": {
    "type": "SMS",
    "id": "a51ebe4e-a412-440e-a8d9-464e68a521cc",
    "message_ref": "ncc5009d",
    "recipient": "447507222200",
    "routed_via": "447507333300",
    "sender": "61481074190",
    "status": "SENT"
  }
}

SMS Inbound Event

{
  "event_type": "SMS_INBOUND",
  "timestamp": "2021-05-06T05:16:33Z",
  "mo": {
    "type": "SMS",
    "id": "alss-2way-605b31c7-d2c49104",
    "message": "Yes, I'm interested",
    "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"
    }
  }
}

last_message is the field that makes two-way messaging work. On receipt of an inbound message, Kudosity looks for a message you sent to that recipient from that sender and attaches it here. Its message_ref is your join key back to whatever the original send belonged to — an order, a booking, a conversation thread.

Route replies on mo.last_message.message_ref, not on the phone number. Number matching breaks the first time one contact is in two flows at once, and it breaks again when a shared number is involved.

It is best-effort — if no recent outbound matches, last_message is absent. Handle that case rather than assuming it's always there.

Shared numbers and routed_via

routed_via appears when a shared local number was used to deliver your message. When it's present, the number the recipient actually replied to is not your sender.

Any logic that pairs an inbound message to an outbound one by comparing sender/recipient needs to account for this — which is the other reason to prefer last_message.message_ref.

Link Hit Event

The payload nests under link_hit, with a running total of hits and the message the link was sent in:

{
  "event_type": "LINK_HIT",
  "timestamp": "2021-07-20T23:14:04Z",
  "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",
      "message_ref": "D301",
      "recipient": "61435795809",
      "sender": "61481074185"
    }
  }
}

For an MMS the source_message additionally carries subject and content_urls.

url is the original destination, not the shortened link. hits is cumulative for that tracked link — so it counts repeat clicks, and is not a unique-recipient count.

Opt-Out Event

{
  "event_type": "OPT_OUT",
  "timestamp": "2021-05-06T05:16:20Z",
  "opt_out": {
    "source": "SMS_INBOUND",
    "source_message": {
      "type": "SMS",
      "id": "a51ebe4e-a412-440e-a8d9-464e68a521cc",
      "message": "Your promo message with opt-out link",
      "message_ref": "ncc5009d",
      "recipient": "61435790000",
      "sender": "61481074190"
    }
  }
}

opt_out.source tells you how they opted out — SMS_INBOUND for a STOP reply, LINK_HIT for the opt-out link. Both are binding; don't treat the link as weaker consent withdrawal than the reply.

Important Notes

• Webhook URLs must use HTTPS
• A successful create returns 201, not 200
• The event_type field at the top level of the request body is deprecated — always use filter.event_type instead
• Rate limit defaults to the system limit if set to 0 or not specified; max is 10,000/sec
• Multiple status events can be triggered for a single message, and they are not guaranteed to arrive in order. Key on status.id and treat handling as idempotent — a message can go SENT → DELIVERED, and a late SENT must not overwrite a recorded DELIVERED.
• Validation errors on this endpoint return a plain {"error": "..."} string, not the RFC 9457 Problem Details object the messaging endpoints use
• Always confirm with the user which event types they need before creating the webhook