Webhooks

Webhook Events

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; for subscription management see Webhook Subscriptions.

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

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 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
2025-01-01

{
  "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
2025-01-01

{
  "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
2025-01-01

{
  "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
2025-01-01

{
  "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; common causes are request timeouts (4001), upstream processing errors, and service unavailability.

2026-02-03
2025-01-01

{
  "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.

2026-02-03

{
  "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
`reaction.removed`	Reaction removed from a message — see Reactions

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

`reaction.added`

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

2026-02-03
2025-01-01

{
  "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
2025-01-01

{
  "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
`chat.typing_indicator.stopped`	Participant stopped typing — see Typing Indicators

Chat-level events use a consistent shape across versions.

`chat.created`

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

2026-02-03
2025-01-01

{
  "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
2025-01-01

{
  "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
2025-01-01

{
  "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 list.

2026-02-03
2025-01-01

{
  "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
2025-01-01

{
  "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.

2026-02-03
2025-01-01

{
  "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
2025-01-01

{
  "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
2025-01-01

{
  "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
2025-01-01

{
  "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

`phone_number.status_updated`

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

2026-02-03
2025-01-01

{
  "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"
  }
}

Webhooks — setup, signature verification, delivery guarantees
Webhook Subscriptions — manage which events each subscription receives
API Reference: Webhook Events — complete payload schemas for every event type

Webhook Events

Webhook envelope

Message events

message.sent

message.received

message.delivered

message.read

message.failed

message.edited

Reaction events

reaction.added

reaction.removed

Chat events

chat.created

chat.group_name_updated

chat.group_icon_updated

chat.group_name_update_failed

chat.group_icon_update_failed

chat.typing_indicator.started

chat.typing_indicator.stopped