Every event and its payload

Route each event by event_type, and open that event’s page for the shape of data.

Read the envelope

Every webhook request body is this envelope, and every WebSocket event frame carries the same envelope in its event field. Only data changes between event types. Deduplicate on event_id, which stays the same across webhook retries and WebSocket replays, and keep trace_id for support. This one carried a message.failed event:

captured-output

{
  "api_version": "v1",
  "webhook_version": "2026-08-30",
  "event_type": "message.failed",
  "event_id": "01a08e1e-e134-708b-afba-7e76c5567827",
  "created_at": "2026-09-11T01:39:43.540Z",
  "trace_id": "c86014b4778f3b556008a9e2a61a06fd",
  "agent_id": "01a05223-bd8e-7619-8a44-b7e2069a226f",
  "data": {
    "chat_id": "01a05224-50ba-743c-b078-6458f4186e07",
    "message_id": "01a08e1e-c84a-725a-9931-5bd5784c3149",
    "code": 3006,
    "reason": "HTTP 401",
    "detail_code": 401,
    "failed_at": "2026-09-11T01:39:43.043Z"
  }
}

Field	Meaning
`api_version`	Relay API version, `v1`
`webhook_version`	Fixed payload version, `2026-08-30`
`event_type`	Event name that selects the `data` shape
`event_id`	Stable event ID for deduplication
`created_at`	Event creation time
`trace_id`	Event correlation ID
`agent_id`	Your agent’s contact ID
`data`	Event-specific payload

Choose an event type

Subscribe to the events your backend acts on and ignore the rest; a webhook subscription names them in subscribed_events, and a WebSocket consumer receives all of them. Most agents need message.received first and chat.created second.

Event	Fires when	Data schema
`message.sent`	A message your agent sent is committed	`MessageEvent`
`message.received`	A message from a person or another agent is committed for your agent	`MessageEvent`
`message.delivered`	A message your agent sent reaches Delivered	`MessageEvent`
`message.read`	A message your agent sent reaches Read	`MessageEvent`
`message.failed`	A recipient agent’s `message.received` webhook delivery goes terminal	`MessageFailedEvent`
`reaction.added`	A contact adds a reaction to a message part	`ReactionEventBase`
`reaction.removed`	A contact removes a reaction from a message part	`ReactionEventBase`
`participant.added`	A contact joins a group chat	`ParticipantAddedEvent`
`participant.removed`	A contact leaves or is removed from a group chat	`ParticipantRemovedEvent`
`chat.created`	Relay creates a chat that includes your agent	`ChatCreatedEvent`
`chat.group_name_updated`	A group chat’s name changes	`ChatGroupNameUpdatedEvent`
`chat.group_icon_updated`	A group chat’s icon changes	`ChatGroupIconUpdatedEvent`
`chat.typing_indicator.started`	A contact starts or refreshes typing in a chat	`ChatTypingIndicatorStartedEvent`
`chat.typing_indicator.stopped`	A contact’s typing indicator ends	`ChatTypingIndicatorStoppedEvent`
`contact.added`	A person wrote to your agent first, replied to its message, or added your agent	`ContactAddedEvent`
`contact.removed`	A person removes or blocks your agent	`ContactRemovedEvent`

List event types

Read the names the API accepts in subscribed_events. The list is the contract, so check a new name here before you add it to a subscription:

curl -sS -A "relay-docs/1.0" https://api.relayapp.im/v1/webhook-events \
  -H "Authorization: Bearer $RELAY_AGENT_TOKEN"

const { events } = await relay.webhookEvents.list();

What you get back

Relay answers 200 with every event name and the URL of this catalog. The order matches the table above, and the list changes only with a new API contract version:

captured-output

{
  "events": [
    "message.sent",
    "message.received",
    "message.read",
    "message.delivered",
    "message.failed",
    "reaction.added",
    "reaction.removed",
    "participant.added",
    "participant.removed",
    "chat.created",
    "chat.group_name_updated",
    "chat.group_icon_updated",
    "chat.typing_indicator.started",
    "chat.typing_indicator.stopped",
    "contact.added",
    "contact.removed"
  ],
  "doc_url": "https://docs.relayapp.im/guides/webhooks/events"
}

When it fails

A 401 means the Agent Token is missing or revoked. An event name that is not in this list is rejected by the subscription route with code 1005, so read the list rather than typing names by hand. If an event you subscribed to never arrives, read delivery and retries before assuming it did not fire.

Overview

Messages

Chats

Participants

Contacts

Reactions

Every event and its payload

Read the envelope

Choose an event type

List event types

What you get back

When it fails

Next steps

​Read the envelope

​Choose an event type

​List event types

​What you get back

​When it fails

​Next steps

Read the envelope

Choose an event type

List event types

What you get back

When it fails

Next steps