Event Types

Every webhook event has a consistent envelope:

{
  "data": {
    "event_type": "<event-type>",
    "id": "<event-or-message-id>",
    "occurred_at": "<ISO-8601 UTC timestamp, e.g. 2025-01-17T10:30:00.278Z>",
    "payload": { /* event-specific payload */ }
  },
  "meta": { "attempt": 1, "max_attempts": 4 }
}

All timestamps (occurred_at, sent_at, delivered_at, failed_at, received_at, clicked_at) are ISO-8601 UTC with millisecond precision and a Z suffix. Phone numbers (to, from) are E.164 strings. The envelope owns the event identity (id, occurred_at); the event-specific payload carries only event fields and resource references (message_id, tracking_link_id).

Identifiers

data.id uniquely identifies the event, and together with event_type it is the delivery deduplication key — if you receive the same (event_type, id) pair twice, treat the second as a redelivery. It also arrives in the X-Event-ID header.

Message events (message.sent, message.delivered, message.failed): id equals message_id — the message is the event identity, since a message emits at most one event of each type. The same id therefore recurs across one message’s lifecycle (message.sent then message.delivered), distinguished by event_type.
message.replied: id equals message_id and identifies the inbound message (the reply itself), not the outbound message it responds to. Correlate via conversation_id.
link.clicked: id is a unique per-click identifier — every unique click delivers its own event. tracking_link_id identifies the link and recurs across clicks of that link.

Test events

Message events include is_test (boolean). It is true for test messages — sent from the app’s test flow or via POST /v1/projects/{id}/test — and for the synthetic event produced by the dashboard’s Send test webhook button (which additionally corresponds to no real message: its ids are random). Production traffic always carries is_test: false. link.clicked has no is_test field.

`message.sent`

Triggered when a message is successfully accepted by the carrier.

{
  "data": {
    "event_type": "message.sent",
    "id": "msg_7f8a9b0c1d2e3f4g",
    "occurred_at": "2025-01-17T10:30:00.278Z",
    "payload": {
      "message_id": "msg_7f8a9b0c1d2e3f4g",
      "conversation_id": "conv_1a2b3c4d5e6f7g8h",
      "project_id": "proj_9i8h7g6f5e4d3c2b",
      "to": "+15551234567",
      "from": "+15559876543",
      "status": "sent",
      "sent_at": "2025-01-17T10:30:00.278Z",
      "message_text": "Hi Jane, thanks for supporting our campaign!",
      "is_test": false,
      "contact": {
        "phone_number": "+15551234567",
        "custom_fields": {
          "First Name": "Jane",
          "Last Name": "Smith",
          "Email": "jane@example.com",
          "City": "Austin",
          "State": "TX"
        }
      }
    }
  },
  "meta": { "attempt": 1, "max_attempts": 4 }
}

`message.delivered`

Triggered when the carrier confirms the message was delivered to the recipient’s device.

{
  "data": {
    "event_type": "message.delivered",
    "id": "msg_7f8a9b0c1d2e3f4g",
    "occurred_at": "2025-01-17T10:30:15.412Z",
    "payload": {
      "message_id": "msg_7f8a9b0c1d2e3f4g",
      "conversation_id": "conv_1a2b3c4d5e6f7g8h",
      "project_id": "proj_9i8h7g6f5e4d3c2b",
      "to": "+15551234567",
      "from": "+15559876543",
      "status": "delivered",
      "sent_at": "2025-01-17T10:30:00.278Z",
      "delivered_at": "2025-01-17T10:30:15.412Z",
      "message_text": "Hi Jane, thanks for supporting our campaign!",
      "is_test": false,
      "contact": {
        "phone_number": "+15551234567",
        "custom_fields": { "First Name": "Jane", "VoterID": "TX12345678" }
      }
    }
  },
  "meta": { "attempt": 1, "max_attempts": 4 }
}

`message.failed`

Triggered when the carrier rejects the message or delivery fails. error_code is a short delivery-failure code (e.g. "300" opted-out, "012" invalid destination) paired with a human-readable error_message. The full list of codes, messages, and how to react to each lives in Delivery error codes. Fields describing a message that was accepted before failing (sent_at, message_text) may be absent when the message was rejected at send time.

{
  "data": {
    "event_type": "message.failed",
    "id": "msg_7f8a9b0c1d2e3f4g",
    "occurred_at": "2025-01-17T10:30:20.007Z",
    "payload": {
      "message_id": "msg_7f8a9b0c1d2e3f4g",
      "conversation_id": "conv_1a2b3c4d5e6f7g8h",
      "project_id": "proj_9i8h7g6f5e4d3c2b",
      "to": "+15551234567",
      "from": "+15559876543",
      "status": "failed",
      "failed_at": "2025-01-17T10:30:20.007Z",
      "error_code": "012",
      "error_message": "Invalid destination number",
      "is_test": false,
      "contact": { "phone_number": "+15551234567", "custom_fields": {} }
    }
  },
  "meta": { "attempt": 1, "max_attempts": 4 }
}

`message.replied`

Triggered when an inbound SMS/MMS is received from a contact.

{
  "data": {
    "event_type": "message.replied",
    "id": "msg_inbound_abc123",
    "occurred_at": "2025-01-17T11:00:00.531Z",
    "payload": {
      "message_id": "msg_inbound_abc123",
      "conversation_id": "conv_1a2b3c4d5e6f7g8h",
      "project_id": "proj_9i8h7g6f5e4d3c2b",
      "from": "+15551234567",
      "to": "+15559876543",
      "text": "Thanks for the update!",
      "media_urls": [],
      "is_opt_out": false,
      "is_opt_in": false,
      "received_at": "2025-01-17T11:00:00.531Z",
      "is_test": false,
      "contact": {
        "phone_number": "+15551234567",
        "custom_fields": { "First Name": "Jane", "Last Name": "Smith" }
      }
    }
  },
  "meta": { "attempt": 1, "max_attempts": 4 }
}

`link.clicked`

Triggered when a recipient clicks a tracking link in your message.

{
  "data": {
    "event_type": "link.clicked",
    "id": "click_xyz789",
    "occurred_at": "2025-01-17T10:35:00.844Z",
    "payload": {
      "tracking_link_id": "link_xyz789",
      "message_id": "msg_7f8a9b0c1d2e3f4g",
      "project_id": "proj_9i8h7g6f5e4d3c2b",
      "short_url": "https://link.yourdomain.com/abc123",
      "destination_url": "https://yoursite.com/volunteer-signup",
      "clicked_at": "2025-01-17T10:35:00.844Z",
      "device": "iPhone",
      "browser": "Safari 17.2",
      "os": "iOS 17.2",
      "ip_address": "203.0.113.42",
      "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_2 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.2 Mobile/15E148 Safari/604.1",
      "is_bot": false,
      "is_unique_click": true,
      "is_share_click": false,
      "contact": {
        "phone_number": "+15551234567",
        "custom_fields": { "First Name": "Jane", "City": "Austin" }
      }
    }
  },
  "meta": { "attempt": 1, "max_attempts": 4 }
}

Introduction

Webhooks

Endpoints

Identifiers

Test events

`message.sent`

`message.delivered`

`message.failed`

`message.replied`

`link.clicked`

​Identifiers

​Test events

​message.sent

​message.delivered

​message.failed

​message.replied

​link.clicked

Identifiers

Test events

`message.sent`

`message.delivered`

`message.failed`

`message.replied`

`link.clicked`