kudosity-webhooks

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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:

| Event Type | Description |
|-----------|-------------|
| `SMS_STATUS` | SMS delivery status changes |
| `SMS_INBOUND` | Inbound SMS received from a recipient |
| `MMS_STATUS` | MMS status changes (currently internal statuses only — SENT, FAILED) |
| `MMS_INBOUND` | Inbound MMS received from a recipient |
| `WHATSAPP_STATUS` | WhatsApp message status changes |
| `WHATSAPP_INBOUND` | Inbound WhatsApp message received from a recipient |
| `RCS_STATUS` | RCS status changes — including `READ` |
| `RCS_INBOUND` | Inbound RCS message received from a recipient |
| `LINK_HIT` | Recipient clicked a tracked link |
| `OPT_OUT` | Recipient opted out via link or STOP message |

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:

| Status | Meaning |
|---|---|
| `SENT` | Submitted to the carrier |
| `ACCEPTED` | Accepted by the carrier; delivery may have been attempted, but is not confirmed |
| `DELIVERED` | Delivered to the handset |
| `FAILED` | Error from the carrier or handset |
| `SOFT_BOUNCE` | Temporarily undeliverable — handset switched off, out of range |
| `HARD_BOUNCE` | Handset disconnected |
| `READ` | Read by the recipient — **RCS only** |
| `OTHER` | Any other status from the carrier |

`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:

| Event type | `sender` / `message_ref` are matched against |
|---|---|
| Status events (`SMS_STATUS`, `RCS_STATUS`, …) | the `status` payload |
| `LINK_HIT` | `link_hit.source_message` |
| `OPT_OUT` | `opt_out.source_message` |
| Inbound events (`SMS_INBOUND`, …) | `sender` matches the **`recipient`** field — the address that received the inbound. `message_ref` and `campaign_id` match `last_message`, when present. |

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

```bash
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

```bash
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`

```bash
curl -s "https://api.transmitmessage.com/v2/webhook" \
  -H "x-api-key: ${KUDOSITY_API_KEY}" \

From kudosity/skills, MIT.

More from kudosity/skills