---
title: Webhook Events | API Docs
description: Event types you can subscribe to, with a representative payload for each category.
---

Every webhook delivered by Linq shares a common envelope with a `data` field specific to the event type. This page lists the event types you can subscribe to and shows a representative payload per category. Each example is sourced directly from the OpenAPI spec — pick a version tab on any example and every other example on the page switches to that version too. For setup, signature verification, and delivery guarantees see [Webhooks](/guides/webhooks/index.md); for subscription management see [Webhook Subscriptions](/guides/webhooks/subscriptions/index.md).

## Webhook envelope

All webhook payloads share a common envelope:

```
{
  "api_version": "v3",
  "webhook_version": "2026-02-03",
  "event_type": "message.received",
  "event_id": "2915e81c-5068-4796-ace2-21d2c94ad298",
  "created_at": "2026-02-05T19:31:13.736Z",
  "trace_id": "8af9171a45022df2eb74ba4e4c83be0f",
  "partner_id": "your-partner-id",
  "data": { ... }
}
```

| Field             | Description                                    |
| ----------------- | ---------------------------------------------- |
| `api_version`     | API version (`v3`)                             |
| `webhook_version` | Payload version (`2025-01-01` or `2026-02-03`) |
| `event_type`      | Event type string                              |
| `event_id`        | Unique event ID (use for deduplication)        |
| `created_at`      | When the event was created                     |
| `trace_id`        | Trace ID for debugging                         |
| `partner_id`      | Your partner identifier                        |
| `data`            | Event-specific payload                         |

## Message events

| Event               | Description                                                                                                                         |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `message.sent`      | Message successfully sent from your phone number                                                                                    |
| `message.received`  | Incoming message received on your phone number                                                                                      |
| `message.delivered` | Message delivered to recipient’s device                                                                                             |
| `message.read`      | Message read by recipient                                                                                                           |
| `message.failed`    | Message delivery failed                                                                                                             |
| `message.edited`    | Message was edited (2026-02-03 version only) — see [Editing messages](/guides/messaging/sending-messages#editing-messages/index.md) |

**Lifecycle timestamps** indicate the event stage:

- `sent_at` — set on `message.sent` and `message.received`
- `delivered_at` — set on `message.delivered`
- `read_at` — set on `message.read`

`message.edited` is only delivered to `2026-02-03` subscriptions.

> **Note:** SMS and MMS sends **do not produce `message.delivered` or `message.read` webhooks** — neither receipt type exists on those protocols. You’ll still get `message.sent` (accepted for delivery) and `message.failed` (hard failure), but treat the absence of a `delivered` event on an SMS fallback as normal, not a bug. See [Protocol capabilities](/guides/messaging/protocol-selection#protocol-capabilities/index.md) for the full matrix.

### `message.sent`

Outbound message confirmed as sent from your phone number. `delivered_at` and `read_at` are still null.

- [2026-02-03](#tab-panel-16)
- [2025-01-01](#tab-panel-17)

```
{
  "api_version": "v3",
  "webhook_version": "2026-02-03",
  "event_type": "message.sent",
  "event_id": "e20feb41-7f67-43f0-89c8-a985cff3b568",
  "created_at": "2026-02-05T19:52:18.101373886Z",
  "trace_id": "2eff5df5c6f688733c007523c4d61cd9",
  "partner_id": "your-partner-id",
  "data": {
    "chat": {
      "id": "0c961e93-e7bf-4db2-bf7b-ea06826bcab4",
      "is_group": false,
      "owner_handle": {
        "handle": "+12025551234",
        "id": "8d79532a-f529-4244-a5cf-d443de051434",
        "is_me": true,
        "joined_at": "2026-01-21T21:59:45.191571Z",
        "left_at": null,
        "service": "iMessage",
        "status": "active"
      }
    },
    "id": "347d62c2-2170-4754-8d30-c76d0c727d96",
    "idempotency_key": null,
    "direction": "outbound",
    "sender_handle": {
      "handle": "+12025551234",
      "id": "8d79532a-f529-4244-a5cf-d443de051434",
      "is_me": true,
      "joined_at": "2026-01-21T21:59:45.191571Z",
      "left_at": null,
      "service": "iMessage",
      "status": "active"
    },
    "parts": [
      {
        "type": "text",
        "value": "Hello from Linq!"
      },
      {
        "filename": "photo.jpg",
        "id": "f13dda7d-ecac-49eb-b3fe-16fe286abf19",
        "mime_type": "image/jpeg",
        "size_bytes": 245678,
        "type": "media",
        "url": "https://cdn.linqapp.com/attachments/a1b2c3d4/photo.jpg?signature=..."
      }
    ],
    "effect": null,
    "sent_at": "2026-02-05T19:52:17.219Z",
    "delivered_at": null,
    "read_at": null,
    "service": "iMessage",
    "preferred_service": null
  }
}
```

```
{
  "api_version": "v3",
  "webhook_version": "2025-01-01",
  "event_type": "message.sent",
  "event_id": "e20feb41-7f67-43f0-89c8-a985cff3b568",
  "created_at": "2026-02-05T19:52:18.101373886Z",
  "trace_id": "2eff5df5c6f688733c007523c4d61cd9",
  "partner_id": "your-partner-id",
  "data": {
    "chat_id": "0c961e93-e7bf-4db2-bf7b-ea06826bcab4",
    "from": "+12025551234",
    "from_handle": {
      "handle": "+12025551234",
      "id": "8d79532a-f529-4244-a5cf-d443de051434",
      "is_me": true,
      "joined_at": "2026-01-21T21:59:45.191571Z",
      "left_at": null,
      "service": "iMessage",
      "status": "active"
    },
    "idempotency_key": null,
    "is_from_me": true,
    "is_group": false,
    "message": {
      "created_at": "2026-02-05T19:52:17.041183Z",
      "delivered_at": null,
      "id": "347d62c2-2170-4754-8d30-c76d0c727d96",
      "is_delivered": false,
      "is_read": false,
      "parts": [
        {
          "type": "text",
          "value": "Hello from Linq!"
        },
        {
          "filename": "photo.gif",
          "id": "f13dda7d-ecac-49eb-b3fe-16fe286abf19",
          "mime_type": "image/gif",
          "size_bytes": 2776819,
          "type": "media",
          "url": "https://cdn.linqapp.com/attachments/example/photo.gif"
        }
      ],
      "read_at": null,
      "sent_at": "2026-02-05T19:52:17.219Z",
      "updated_at": "2026-02-05T19:52:18.084038Z"
    },
    "preferred_service": null,
    "received_at": null,
    "recipient_handle": null,
    "recipient_phone": null,
    "service": "iMessage"
  }
}
```

### `message.received`

Inbound message from a participant. Contains the full message content and any attachments.

- [2026-02-03](#tab-panel-18)
- [2025-01-01](#tab-panel-19)

```
{
  "api_version": "v3",
  "webhook_version": "2026-02-03",
  "event_type": "message.received",
  "event_id": "2915e81c-5068-4796-ace2-21d2c94ad298",
  "created_at": "2026-02-05T19:31:13.736444093Z",
  "trace_id": "8af9171a45022df2eb74ba4e4c83be0f",
  "partner_id": "your-partner-id",
  "data": {
    "chat": {
      "id": "8f392755-6865-4b18-880a-227f9d8b458f",
      "is_group": false,
      "owner_handle": {
        "handle": "+12025551234",
        "id": "6d6c617f-187a-4dcd-a0d5-988347a8c092",
        "is_me": true,
        "joined_at": "2026-01-04T05:48:51.321469Z",
        "left_at": null,
        "service": "iMessage",
        "status": "active"
      }
    },
    "id": "89e3566e-1d13-49e5-a8ee-48490d5bfeb7",
    "direction": "inbound",
    "sender_handle": {
      "handle": "+12025559876",
      "id": "e604375a-5913-483a-8278-c631e8f0ffda",
      "is_me": false,
      "joined_at": "2026-01-04T05:48:51.321469Z",
      "left_at": null,
      "service": "iMessage",
      "status": "active"
    },
    "parts": [
      {
        "type": "text",
        "value": "Hello!"
      }
    ],
    "effect": null,
    "reply_to": null,
    "sent_at": "2026-02-05T19:31:13.074Z",
    "delivered_at": null,
    "read_at": null,
    "service": "iMessage"
  }
}
```

```
{
  "api_version": "v3",
  "webhook_version": "2025-01-01",
  "event_type": "message.received",
  "event_id": "2915e81c-5068-4796-ace2-21d2c94ad298",
  "created_at": "2026-02-05T19:31:13.736444093Z",
  "trace_id": "8af9171a45022df2eb74ba4e4c83be0f",
  "partner_id": "your-partner-id",
  "data": {
    "chat_id": "8f392755-6865-4b18-880a-227f9d8b458f",
    "from": "+12025559876",
    "from_handle": {
      "handle": "+12025559876",
      "id": "e604375a-5913-483a-8278-c631e8f0ffda",
      "is_me": false,
      "joined_at": "2026-01-04T05:48:51.321469Z",
      "left_at": null,
      "service": "iMessage",
      "status": "active"
    },
    "idempotency_key": null,
    "is_from_me": false,
    "is_group": false,
    "message": {
      "created_at": "2026-02-05T19:31:12.892Z",
      "delivered_at": null,
      "id": "89e3566e-1d13-49e5-a8ee-48490d5bfeb7",
      "is_delivered": false,
      "is_read": false,
      "parts": [
        {
          "type": "text",
          "value": "Hello!"
        }
      ],
      "read_at": null,
      "sent_at": "2026-02-05T19:31:13.074Z",
      "updated_at": "2026-02-05T19:31:13.712Z"
    },
    "preferred_service": null,
    "received_at": "2026-02-05T19:31:13.074Z",
    "recipient_handle": {
      "handle": "+12025551234",
      "id": "6d6c617f-187a-4dcd-a0d5-988347a8c092",
      "is_me": true,
      "joined_at": "2026-01-04T05:48:51.321469Z",
      "left_at": null,
      "service": "iMessage",
      "status": "active"
    },
    "recipient_phone": null,
    "service": "iMessage"
  }
}
```

### `message.delivered`

Outbound message reached the recipient’s device. Fires on iMessage and RCS — not on SMS/MMS, which have no delivery receipt mechanism.

- [2026-02-03](#tab-panel-20)
- [2025-01-01](#tab-panel-21)

```
{
  "api_version": "v3",
  "webhook_version": "2026-02-03",
  "event_type": "message.delivered",
  "event_id": "67c4ad39-e9b0-47f6-82f8-64bdd8ceafa6",
  "created_at": "2026-02-05T19:52:22.593689073Z",
  "trace_id": "abde7f6248fba00f97e8c7dc4782d7e0",
  "partner_id": "your-partner-id",
  "data": {
    "chat": {
      "id": "0c961e93-e7bf-4db2-bf7b-ea06826bcab4",
      "is_group": false,
      "owner_handle": {
        "handle": "+12025551234",
        "id": "8d79532a-f529-4244-a5cf-d443de051434",
        "is_me": true,
        "joined_at": "2026-01-21T21:59:45.191571Z",
        "left_at": null,
        "service": "iMessage",
        "status": "active"
      }
    },
    "id": "347d62c2-2170-4754-8d30-c76d0c727d96",
    "idempotency_key": null,
    "direction": "outbound",
    "sender_handle": {
      "handle": "+12025551234",
      "id": "8d79532a-f529-4244-a5cf-d443de051434",
      "is_me": true,
      "joined_at": "2026-01-21T21:59:45.191571Z",
      "left_at": null,
      "service": "iMessage",
      "status": "active"
    },
    "parts": [
      {
        "type": "text",
        "value": "Hello from Linq!"
      },
      {
        "filename": "photo.gif",
        "id": "f13dda7d-ecac-49eb-b3fe-16fe286abf19",
        "mime_type": "image/gif",
        "size_bytes": 2776819,
        "type": "media",
        "url": "https://cdn.linqapp.com/attachments/f13dda7d/photo.gif?signature=..."
      }
    ],
    "effect": null,
    "sent_at": "2026-02-05T19:52:17.219Z",
    "delivered_at": "2026-02-05T19:52:22.291Z",
    "read_at": null,
    "service": "iMessage",
    "preferred_service": null
  }
}
```

```
{
  "api_version": "v3",
  "webhook_version": "2025-01-01",
  "event_type": "message.delivered",
  "event_id": "67c4ad39-e9b0-47f6-82f8-64bdd8ceafa6",
  "created_at": "2026-02-05T19:52:22.593689073Z",
  "trace_id": "abde7f6248fba00f97e8c7dc4782d7e0",
  "partner_id": "your-partner-id",
  "data": {
    "chat_id": "0c961e93-e7bf-4db2-bf7b-ea06826bcab4",
    "from": "+12025551234",
    "from_handle": {
      "handle": "+12025551234",
      "id": "8d79532a-f529-4244-a5cf-d443de051434",
      "is_me": true,
      "joined_at": "2026-01-21T21:59:45.191571Z",
      "left_at": null,
      "service": "iMessage",
      "status": "active"
    },
    "idempotency_key": null,
    "is_from_me": true,
    "is_group": false,
    "message": {
      "created_at": "2026-02-05T19:52:17.041183Z",
      "delivered_at": "2026-02-05T19:52:22.291Z",
      "id": "347d62c2-2170-4754-8d30-c76d0c727d96",
      "is_delivered": true,
      "is_read": false,
      "parts": [
        {
          "type": "text",
          "value": "Hello from Linq!"
        },
        {
          "filename": "photo.gif",
          "id": "f13dda7d-ecac-49eb-b3fe-16fe286abf19",
          "mime_type": "image/gif",
          "size_bytes": 2776819,
          "type": "media",
          "url": "https://cdn.linqapp.com/attachments/example/photo.gif"
        }
      ],
      "read_at": null,
      "sent_at": "2026-02-05T19:52:17.219Z",
      "updated_at": "2026-02-05T19:52:22.571Z"
    },
    "delivered_at": "2026-02-05T19:52:22.291Z",
    "message_id": "347d62c2-2170-4754-8d30-c76d0c727d96",
    "preferred_service": null,
    "received_at": null,
    "recipient_handle": null,
    "recipient_phone": null,
    "service": "iMessage"
  }
}
```

### `message.read`

Outbound message was read by the recipient. Fires on iMessage and RCS (not SMS/MMS), and requires the recipient to have read receipts enabled on their device.

- [2026-02-03](#tab-panel-22)
- [2025-01-01](#tab-panel-23)

```
{
  "api_version": "v3",
  "webhook_version": "2026-02-03",
  "event_type": "message.read",
  "event_id": "8fd42065-b998-482a-93b3-da855f8dad17",
  "created_at": "2026-02-05T19:13:58.833366566Z",
  "trace_id": "cbb93c08fa1a3f3c4c2efc161d67f36d",
  "partner_id": "your-partner-id",
  "data": {
    "chat": {
      "id": "24e33345-e6cf-4f50-9d35-1d7fde8c9818",
      "is_group": false,
      "owner_handle": {
        "handle": "+12025551234",
        "id": "d31678e9-0442-48fd-b7ed-c898d245dd15",
        "is_me": true,
        "joined_at": "2026-01-18T03:38:41.442254Z",
        "left_at": null,
        "service": "iMessage",
        "status": "active"
      }
    },
    "id": "dc6d3f68-90df-48f0-a504-e65f239a383c",
    "idempotency_key": null,
    "direction": "outbound",
    "sender_handle": {
      "handle": "+12025551234",
      "id": "d31678e9-0442-48fd-b7ed-c898d245dd15",
      "is_me": true,
      "joined_at": "2026-01-18T03:38:41.442254Z",
      "left_at": null,
      "service": "iMessage",
      "status": "active"
    },
    "parts": [
      {
        "type": "text",
        "value": "Hello world!"
      }
    ],
    "effect": null,
    "sent_at": "2026-02-05T19:13:57.814Z",
    "delivered_at": "2026-02-05T19:13:57.948Z",
    "read_at": "2026-02-05T19:13:58.177Z",
    "service": "iMessage",
    "preferred_service": null
  }
}
```

```
{
  "api_version": "v3",
  "webhook_version": "2025-01-01",
  "event_type": "message.read",
  "event_id": "8fd42065-b998-482a-93b3-da855f8dad17",
  "created_at": "2026-02-05T19:13:58.833366566Z",
  "trace_id": "cbb93c08fa1a3f3c4c2efc161d67f36d",
  "partner_id": "your-partner-id",
  "data": {
    "chat_id": "24e33345-e6cf-4f50-9d35-1d7fde8c9818",
    "from": "+12025551234",
    "from_handle": {
      "handle": "+12025551234",
      "id": "d31678e9-0442-48fd-b7ed-c898d245dd15",
      "is_me": true,
      "joined_at": "2026-01-18T03:38:41.442254Z",
      "left_at": null,
      "service": "iMessage",
      "status": "active"
    },
    "idempotency_key": null,
    "is_from_me": true,
    "is_group": false,
    "message": {
      "created_at": "2026-02-05T19:13:57.612Z",
      "delivered_at": "2026-02-05T19:13:57.948Z",
      "id": "dc6d3f68-90df-48f0-a504-e65f239a383c",
      "is_delivered": true,
      "is_read": true,
      "parts": [
        {
          "type": "text",
          "value": "Hello world!"
        }
      ],
      "read_at": "2026-02-05T19:13:58.177Z",
      "sent_at": "2026-02-05T19:13:57.814Z",
      "updated_at": "2026-02-05T19:13:58.811Z"
    },
    "message_id": "dc6d3f68-90df-48f0-a504-e65f239a383c",
    "preferred_service": null,
    "read_at": "2026-02-05T19:13:58.177Z",
    "received_at": null,
    "recipient_handle": null,
    "recipient_phone": null,
    "service": "iMessage"
  }
}
```

### `message.failed`

Message delivery failed. `code` maps to an [error code](/error/index.md); common causes are request timeouts (`4001`), upstream processing errors, and service unavailability.

- [2026-02-03](#tab-panel-24)
- [2025-01-01](#tab-panel-25)

```
{
  "api_version": "v3",
  "webhook_version": "2026-02-03",
  "event_type": "message.failed",
  "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2025-11-23T17:35:00.000Z",
  "trace_id": "abc123def456",
  "partner_id": "your-partner-id",
  "data": {
    "chat_id": "550e8400-e29b-41d4-a716-446655440000",
    "message_id": "550e8400-e29b-41d4-a716-446655440001",
    "code": 4001,
    "reason": "Delivery failed",
    "failed_at": "2025-11-23T17:35:00.000Z"
  }
}
```

```
{
  "api_version": "v3",
  "webhook_version": "2025-01-01",
  "event_type": "message.failed",
  "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2025-11-23T17:35:00.000Z",
  "trace_id": "abc123def456",
  "partner_id": "your-partner-id",
  "data": {
    "chat_id": "550e8400-e29b-41d4-a716-446655440000",
    "message_id": "550e8400-e29b-41d4-a716-446655440001",
    "code": 4001,
    "reason": "Delivery failed",
    "failed_at": "2025-11-23T17:35:00.000Z"
  }
}
```

### `message.edited`

A text part of a previously sent message was edited. Only delivered to subscriptions on `webhook_version: "2026-02-03"` — see [Editing messages](/guides/messaging/sending-messages#editing-messages/index.md).

- [2026-02-03](#tab-panel-15)

```
{
  "api_version": "v3",
  "webhook_version": "2026-02-03",
  "event_type": "message.edited",
  "event_id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
  "created_at": "2026-03-05T02:12:46.501Z",
  "trace_id": "d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6",
  "partner_id": "your-partner-id",
  "data": {
    "chat": {
      "id": "8f392755-6865-4b18-880a-227f9d8b458f",
      "is_group": false,
      "owner_handle": {
        "handle": "+12025551234",
        "id": "6d6c617f-187a-4dcd-a0d5-988347a8c092",
        "is_me": true,
        "joined_at": "2026-01-04T05:48:51.321469Z",
        "left_at": null,
        "service": "iMessage",
        "status": "active"
      }
    },
    "id": "89e3566e-1d13-49e5-a8ee-48490d5bfeb7",
    "direction": "outbound",
    "sender_handle": {
      "handle": "+12025551234",
      "id": "6d6c617f-187a-4dcd-a0d5-988347a8c092",
      "is_me": true,
      "joined_at": "2026-01-04T05:48:51.321469Z",
      "left_at": null,
      "service": "iMessage",
      "status": "active"
    },
    "part": {
      "index": 0,
      "text": "This is the edited message content"
    },
    "edited_at": "2026-03-05T02:12:46.487Z"
  }
}
```

## Reaction events

| Event              | Description                                                                                   |
| ------------------ | --------------------------------------------------------------------------------------------- |
| `reaction.added`   | Reaction (tapback) added to a message — see [Reactions](/guides/messaging/reactions/index.md) |
| `reaction.removed` | Reaction removed from a message — see [Reactions](/guides/messaging/reactions/index.md)       |

Both events share the `ReactionEventBase` shape and are identical across versions. The `reaction_type` field indicates the kind of reaction:

- **Tapback** — one of `love`, `like`, `dislike`, `laugh`, `emphasize`, `question`
- **Custom emoji** — `reaction_type: "custom"`, emoji in `custom_emoji`
- **Sticker** — `reaction_type: "sticker"`, details in a `sticker` object — see [Sticker attachments](/guides/messaging/reactions#sticker-attachments/index.md)

### `reaction.added`

A standard tapback (`love`) added to a message part.

- [2026-02-03](#tab-panel-26)
- [2025-01-01](#tab-panel-27)

```
{
  "api_version": "v3",
  "webhook_version": "2026-02-03",
  "event_type": "reaction.added",
  "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2025-11-23T17:35:00.000Z",
  "trace_id": "abc123def456",
  "partner_id": "your-partner-id",
  "data": {
    "chat_id": "550e8400-e29b-41d4-a716-446655440000",
    "message_id": "550e8400-e29b-41d4-a716-446655440001",
    "part_index": 0,
    "reaction_type": "love",
    "custom_emoji": null,
    "is_from_me": false,
    "from": "+14155559876",
    "from_handle": {
      "id": "550e8400-e29b-41d4-a716-446655440011",
      "handle": "+14155559876",
      "is_me": false,
      "service": "iMessage",
      "status": "active",
      "joined_at": "2025-11-23T17:30:00.000Z",
      "left_at": null
    },
    "service": "iMessage",
    "reacted_at": "2025-11-23T17:35:00.000Z",
    "sticker": null
  }
}
```

```
{
  "api_version": "v3",
  "webhook_version": "2025-01-01",
  "event_type": "reaction.added",
  "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2025-11-23T17:35:00.000Z",
  "trace_id": "abc123def456",
  "partner_id": "your-partner-id",
  "data": {
    "chat_id": "550e8400-e29b-41d4-a716-446655440000",
    "message_id": "550e8400-e29b-41d4-a716-446655440001",
    "part_index": 0,
    "reaction_type": "love",
    "custom_emoji": null,
    "is_from_me": false,
    "from": "+14155559876",
    "from_handle": {
      "id": "550e8400-e29b-41d4-a716-446655440011",
      "handle": "+14155559876",
      "is_me": false,
      "service": "iMessage",
      "status": "active",
      "joined_at": "2025-11-23T17:30:00.000Z",
      "left_at": null
    },
    "service": "iMessage",
    "reacted_at": "2025-11-23T17:35:00.000Z",
    "sticker": null
  }
}
```

### `reaction.removed`

Same shape as `reaction.added` — `reacted_at` is when the reaction was taken off.

- [2026-02-03](#tab-panel-28)
- [2025-01-01](#tab-panel-29)

```
{
  "api_version": "v3",
  "webhook_version": "2026-02-03",
  "event_type": "reaction.removed",
  "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2025-11-23T17:35:00.000Z",
  "trace_id": "abc123def456",
  "partner_id": "your-partner-id",
  "data": {
    "chat_id": "550e8400-e29b-41d4-a716-446655440000",
    "message_id": "550e8400-e29b-41d4-a716-446655440001",
    "part_index": 0,
    "reaction_type": "love",
    "custom_emoji": null,
    "is_from_me": false,
    "from": "+14155559876",
    "from_handle": {
      "id": "550e8400-e29b-41d4-a716-446655440011",
      "handle": "+14155559876",
      "is_me": false,
      "service": "iMessage",
      "status": "active",
      "joined_at": "2025-11-23T17:30:00.000Z",
      "left_at": null
    },
    "service": "iMessage",
    "reacted_at": "2025-11-23T17:35:00.000Z",
    "sticker": null
  }
}
```

```
{
  "api_version": "v3",
  "webhook_version": "2025-01-01",
  "event_type": "reaction.removed",
  "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2025-11-23T17:35:00.000Z",
  "trace_id": "abc123def456",
  "partner_id": "your-partner-id",
  "data": {
    "chat_id": "550e8400-e29b-41d4-a716-446655440000",
    "message_id": "550e8400-e29b-41d4-a716-446655440001",
    "part_index": 0,
    "reaction_type": "love",
    "custom_emoji": null,
    "is_from_me": false,
    "from": "+14155559876",
    "from_handle": {
      "id": "550e8400-e29b-41d4-a716-446655440011",
      "handle": "+14155559876",
      "is_me": false,
      "service": "iMessage",
      "status": "active",
      "joined_at": "2025-11-23T17:30:00.000Z",
      "left_at": null
    },
    "service": "iMessage",
    "reacted_at": "2025-11-23T17:35:00.000Z",
    "sticker": null
  }
}
```

## Chat events

| Event                           | Description                                                                                    |
| ------------------------------- | ---------------------------------------------------------------------------------------------- |
| `chat.created`                  | New chat created — fires for DMs and group chats                                               |
| `chat.group_name_updated`       | Group chat display name changed                                                                |
| `chat.group_icon_updated`       | Group chat icon changed                                                                        |
| `chat.group_name_update_failed` | Group name update failed                                                                       |
| `chat.group_icon_update_failed` | Group icon update failed                                                                       |
| `chat.typing_indicator.started` | Participant started typing — see [Typing Indicators](/guides/chats/typing-indicators/index.md) |
| `chat.typing_indicator.stopped` | Participant stopped typing — see [Typing Indicators](/guides/chats/typing-indicators/index.md) |

Chat-level events use a consistent shape across versions.

### `chat.created`

The `data` block mirrors the `GET /v3/chats/{chatId}` response.

- [2026-02-03](#tab-panel-30)
- [2025-01-01](#tab-panel-31)

```
{
  "api_version": "v3",
  "webhook_version": "2026-02-03",
  "event_type": "chat.created",
  "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2025-11-23T17:35:00.000Z",
  "trace_id": "abc123def456",
  "partner_id": "your-partner-id",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "display_name": "+14155551234, +14155559876",
    "service": "iMessage",
    "handles": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440010",
        "handle": "+14155551234",
        "is_me": true,
        "service": "iMessage",
        "status": "active",
        "joined_at": "2025-11-23T17:30:00.000Z",
        "left_at": null
      },
      {
        "id": "550e8400-e29b-41d4-a716-446655440011",
        "handle": "+14155559876",
        "is_me": false,
        "service": "iMessage",
        "status": "active",
        "joined_at": "2025-11-23T17:30:00.000Z",
        "left_at": null
      }
    ],
    "is_group": false,
    "created_at": "2025-11-23T17:30:00.000Z",
    "updated_at": "2025-11-23T17:30:00.000Z"
  }
}
```

```
{
  "api_version": "v3",
  "webhook_version": "2025-01-01",
  "event_type": "chat.created",
  "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2025-11-23T17:35:00.000Z",
  "trace_id": "abc123def456",
  "partner_id": "your-partner-id",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "display_name": "+14155551234, +14155559876",
    "service": "iMessage",
    "handles": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440010",
        "handle": "+14155551234",
        "is_me": true,
        "service": "iMessage",
        "status": "active",
        "joined_at": "2025-11-23T17:30:00.000Z",
        "left_at": null
      },
      {
        "id": "550e8400-e29b-41d4-a716-446655440011",
        "handle": "+14155559876",
        "is_me": false,
        "service": "iMessage",
        "status": "active",
        "joined_at": "2025-11-23T17:30:00.000Z",
        "left_at": null
      }
    ],
    "is_group": false,
    "created_at": "2025-11-23T17:30:00.000Z",
    "updated_at": "2025-11-23T17:30:00.000Z"
  }
}
```

### `chat.group_name_updated`

`new_value` is `null` when the name was removed; `old_value` is `null` when no previous name existed.

- [2026-02-03](#tab-panel-32)
- [2025-01-01](#tab-panel-33)

```
{
  "api_version": "v3",
  "webhook_version": "2026-02-03",
  "event_type": "chat.group_name_updated",
  "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2025-11-23T17:35:00.000Z",
  "trace_id": "abc123def456",
  "partner_id": "your-partner-id",
  "data": {
    "chat_id": "550e8400-e29b-41d4-a716-446655440000",
    "old_value": "Old Group Name",
    "new_value": "New Group Name",
    "changed_by_handle": {
      "id": "550e8400-e29b-41d4-a716-446655440011",
      "handle": "+14155559876",
      "is_me": false,
      "service": "iMessage",
      "status": "active",
      "joined_at": "2025-11-23T17:30:00.000Z",
      "left_at": null
    },
    "updated_at": "2025-11-23T17:50:00.000Z"
  }
}
```

```
{
  "api_version": "v3",
  "webhook_version": "2025-01-01",
  "event_type": "chat.group_name_updated",
  "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2025-11-23T17:35:00.000Z",
  "trace_id": "abc123def456",
  "partner_id": "your-partner-id",
  "data": {
    "chat_id": "550e8400-e29b-41d4-a716-446655440000",
    "old_value": "Old Group Name",
    "new_value": "New Group Name",
    "changed_by_handle": {
      "id": "550e8400-e29b-41d4-a716-446655440011",
      "handle": "+14155559876",
      "is_me": false,
      "service": "iMessage",
      "status": "active",
      "joined_at": "2025-11-23T17:30:00.000Z",
      "left_at": null
    },
    "updated_at": "2025-11-23T17:50:00.000Z"
  }
}
```

### `chat.group_icon_updated`

Same shape as `chat.group_name_updated`; `old_value` and `new_value` are image URLs (null when absent).

- [2026-02-03](#tab-panel-34)
- [2025-01-01](#tab-panel-35)

```
{
  "api_version": "v3",
  "webhook_version": "2026-02-03",
  "event_type": "chat.group_icon_updated",
  "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2025-11-23T17:35:00.000Z",
  "trace_id": "abc123def456",
  "partner_id": "your-partner-id",
  "data": {
    "chat_id": "550e8400-e29b-41d4-a716-446655440000",
    "old_value": "https://example.com/old-icon.png",
    "new_value": "https://example.com/new-icon.png",
    "changed_by_handle": {
      "id": "550e8400-e29b-41d4-a716-446655440011",
      "handle": "+14155559876",
      "is_me": false,
      "service": "iMessage",
      "status": "active",
      "joined_at": "2025-11-23T17:30:00.000Z",
      "left_at": null
    },
    "updated_at": "2025-11-23T17:50:00.000Z"
  }
}
```

```
{
  "api_version": "v3",
  "webhook_version": "2025-01-01",
  "event_type": "chat.group_icon_updated",
  "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2025-11-23T17:35:00.000Z",
  "trace_id": "abc123def456",
  "partner_id": "your-partner-id",
  "data": {
    "chat_id": "550e8400-e29b-41d4-a716-446655440000",
    "old_value": "https://example.com/old-icon.png",
    "new_value": "https://example.com/new-icon.png",
    "changed_by_handle": {
      "id": "550e8400-e29b-41d4-a716-446655440011",
      "handle": "+14155559876",
      "is_me": false,
      "service": "iMessage",
      "status": "active",
      "joined_at": "2025-11-23T17:30:00.000Z",
      "left_at": null
    },
    "updated_at": "2025-11-23T17:50:00.000Z"
  }
}
```

### `chat.group_name_update_failed`

Fires when a `PUT /v3/chats/{chatId}` request to change the display name couldn’t be applied. `error_code` follows the standard [error code](/error/index.md) list.

- [2026-02-03](#tab-panel-36)
- [2025-01-01](#tab-panel-37)

```
{
  "api_version": "v3",
  "webhook_version": "2026-02-03",
  "event_type": "chat.group_name_update_failed",
  "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2025-11-23T17:35:00.000Z",
  "trace_id": "abc123def456",
  "partner_id": "your-partner-id",
  "data": {
    "chat_id": "550e8400-e29b-41d4-a716-446655440000",
    "error_code": 3007,
    "failed_at": "2025-11-23T17:55:00.000Z"
  }
}
```

```
{
  "api_version": "v3",
  "webhook_version": "2025-01-01",
  "event_type": "chat.group_name_update_failed",
  "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2025-11-23T17:35:00.000Z",
  "trace_id": "abc123def456",
  "partner_id": "your-partner-id",
  "data": {
    "chat_id": "550e8400-e29b-41d4-a716-446655440000",
    "error_code": 3007,
    "failed_at": "2025-11-23T17:55:00.000Z"
  }
}
```

### `chat.group_icon_update_failed`

Identical shape to `chat.group_name_update_failed`, fired when the group icon update couldn’t be applied.

- [2026-02-03](#tab-panel-38)
- [2025-01-01](#tab-panel-39)

```
{
  "api_version": "v3",
  "webhook_version": "2026-02-03",
  "event_type": "chat.group_icon_update_failed",
  "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2025-11-23T17:35:00.000Z",
  "trace_id": "abc123def456",
  "partner_id": "your-partner-id",
  "data": {
    "chat_id": "550e8400-e29b-41d4-a716-446655440000",
    "error_code": 3007,
    "failed_at": "2025-11-23T17:55:00.000Z"
  }
}
```

```
{
  "api_version": "v3",
  "webhook_version": "2025-01-01",
  "event_type": "chat.group_icon_update_failed",
  "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2025-11-23T17:35:00.000Z",
  "trace_id": "abc123def456",
  "partner_id": "your-partner-id",
  "data": {
    "chat_id": "550e8400-e29b-41d4-a716-446655440000",
    "error_code": 3007,
    "failed_at": "2025-11-23T17:55:00.000Z"
  }
}
```

### `chat.typing_indicator.started`

Fires when a participant starts typing in a one-to-one chat. Not emitted for group chats — see [Typing Indicators](/guides/chats/typing-indicators/index.md).

- [2026-02-03](#tab-panel-40)
- [2025-01-01](#tab-panel-41)

```
{
  "api_version": "v3",
  "webhook_version": "2026-02-03",
  "event_type": "chat.typing_indicator.started",
  "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2025-11-23T17:35:00.000Z",
  "trace_id": "abc123def456",
  "partner_id": "your-partner-id",
  "data": {
    "chat_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}
```

```
{
  "api_version": "v3",
  "webhook_version": "2025-01-01",
  "event_type": "chat.typing_indicator.started",
  "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2025-11-23T17:35:00.000Z",
  "trace_id": "abc123def456",
  "partner_id": "your-partner-id",
  "data": {
    "chat_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}
```

### `chat.typing_indicator.stopped`

Counterpart to `chat.typing_indicator.started`. Also fires automatically when the participant sends the message they were typing.

- [2026-02-03](#tab-panel-42)
- [2025-01-01](#tab-panel-43)

```
{
  "api_version": "v3",
  "webhook_version": "2026-02-03",
  "event_type": "chat.typing_indicator.stopped",
  "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2025-11-23T17:35:00.000Z",
  "trace_id": "abc123def456",
  "partner_id": "your-partner-id",
  "data": {
    "chat_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}
```

```
{
  "api_version": "v3",
  "webhook_version": "2025-01-01",
  "event_type": "chat.typing_indicator.stopped",
  "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2025-11-23T17:35:00.000Z",
  "trace_id": "abc123def456",
  "partner_id": "your-partner-id",
  "data": {
    "chat_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}
```

## Participant events

| Event                 | Description                           |
| --------------------- | ------------------------------------- |
| `participant.added`   | Participant added to a group chat     |
| `participant.removed` | Participant removed from a group chat |

Participant events share the same shape across versions.

### `participant.added`

Fires when a new participant joins a group chat.

- [2026-02-03](#tab-panel-44)
- [2025-01-01](#tab-panel-45)

```
{
  "api_version": "v3",
  "webhook_version": "2026-02-03",
  "event_type": "participant.added",
  "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2025-11-23T17:35:00.000Z",
  "trace_id": "abc123def456",
  "partner_id": "your-partner-id",
  "data": {
    "chat_id": "550e8400-e29b-41d4-a716-446655440000",
    "handle": "+14155559876",
    "participant": {
      "id": "550e8400-e29b-41d4-a716-446655440011",
      "handle": "+14155559876",
      "is_me": false,
      "service": "iMessage",
      "status": "active",
      "joined_at": "2025-11-23T17:40:00.000Z",
      "left_at": null
    },
    "added_at": "2025-11-23T17:40:00.000Z"
  }
}
```

```
{
  "api_version": "v3",
  "webhook_version": "2025-01-01",
  "event_type": "participant.added",
  "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2025-11-23T17:35:00.000Z",
  "trace_id": "abc123def456",
  "partner_id": "your-partner-id",
  "data": {
    "chat_id": "550e8400-e29b-41d4-a716-446655440000",
    "handle": "+14155559876",
    "participant": {
      "id": "550e8400-e29b-41d4-a716-446655440011",
      "handle": "+14155559876",
      "is_me": false,
      "service": "iMessage",
      "status": "active",
      "joined_at": "2025-11-23T17:40:00.000Z",
      "left_at": null
    },
    "added_at": "2025-11-23T17:40:00.000Z"
  }
}
```

### `participant.removed`

Fires when a participant leaves or is removed from a group chat. The `participant` object’s `status` is `removed` and `left_at` is set.

- [2026-02-03](#tab-panel-46)
- [2025-01-01](#tab-panel-47)

```
{
  "api_version": "v3",
  "webhook_version": "2026-02-03",
  "event_type": "participant.removed",
  "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2025-11-23T17:35:00.000Z",
  "trace_id": "abc123def456",
  "partner_id": "your-partner-id",
  "data": {
    "chat_id": "550e8400-e29b-41d4-a716-446655440000",
    "handle": "+14155559876",
    "participant": {
      "id": "550e8400-e29b-41d4-a716-446655440011",
      "handle": "+14155559876",
      "is_me": false,
      "service": "iMessage",
      "status": "removed",
      "joined_at": "2025-11-23T17:30:00.000Z",
      "left_at": "2025-11-23T17:45:00.000Z"
    },
    "removed_at": "2025-11-23T17:45:00.000Z"
  }
}
```

```
{
  "api_version": "v3",
  "webhook_version": "2025-01-01",
  "event_type": "participant.removed",
  "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2025-11-23T17:35:00.000Z",
  "trace_id": "abc123def456",
  "partner_id": "your-partner-id",
  "data": {
    "chat_id": "550e8400-e29b-41d4-a716-446655440000",
    "handle": "+14155559876",
    "participant": {
      "id": "550e8400-e29b-41d4-a716-446655440011",
      "handle": "+14155559876",
      "is_me": false,
      "service": "iMessage",
      "status": "removed",
      "joined_at": "2025-11-23T17:30:00.000Z",
      "left_at": "2025-11-23T17:45:00.000Z"
    },
    "removed_at": "2025-11-23T17:45:00.000Z"
  }
}
```

## Phone number events

| Event                         | Description                                                                                                      |
| ----------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `phone_number.status_updated` | Phone number status changed between `ACTIVE` and `FLAGGED` — see [Phone Numbers](/guides/phone-numbers/index.md) |

### `phone_number.status_updated`

Fires when a phone number moves between `ACTIVE` and `FLAGGED` states.

- [2026-02-03](#tab-panel-48)
- [2025-01-01](#tab-panel-49)

```
{
  "api_version": "v3",
  "webhook_version": "2026-02-03",
  "event_type": "phone_number.status_updated",
  "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2026-02-18T18:35:05.363Z",
  "trace_id": "b66e67c5c6b2c20e41d53c51698db27a",
  "partner_id": "your-partner-id",
  "data": {
    "phone_number": "+12025551234",
    "previous_status": "ACTIVE",
    "new_status": "FLAGGED",
    "changed_at": "2026-02-18T18:35:05.000Z"
  }
}
```

```
{
  "api_version": "v3",
  "webhook_version": "2025-01-01",
  "event_type": "phone_number.status_updated",
  "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2026-02-18T18:35:05.363Z",
  "trace_id": "b66e67c5c6b2c20e41d53c51698db27a",
  "partner_id": "your-partner-id",
  "data": {
    "phone_number": "+12025551234",
    "previous_status": "ACTIVE",
    "new_status": "FLAGGED",
    "changed_at": "2026-02-18T18:35:05.000Z"
  }
}
```

## Related

- [Webhooks](/guides/webhooks/index.md) — setup, signature verification, delivery guarantees
- [Webhook Subscriptions](/guides/webhooks/subscriptions/index.md) — manage which events each subscription receives
- [API Reference: Webhook Events](/api/resources/webhooks/index.md) — complete payload schemas for every event type