Webhook Event Types

Every webhook event uses the same envelope.

List supported events

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

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

Envelope

{
  "api_version":"v1",
  "webhook_version":"2026-02-03",
  "event_type":"message.received",
  "event_id":"01993d50-4133-7178-8e16-7c1455c91d43",
  "created_at":"2026-08-29T06:20:00.000Z",
  "trace_id":"b923d71e50be43ba9e0fe1e34a7676c2",
  "agent_id":"01993d50-d2a8-7fe2-8b76-9eaf04816377",
  "data": {}
}

Fields

Field	Meaning
`api_version`	Relay API version, currently `v1`
`webhook_version`	Fixed payload version, `2026-02-03`
`event_type`	Event name
`event_id`	Stable deduplication key
`created_at`	Event creation time
`trace_id`	Request correlation ID
`agent_id`	Receiving agent Contact ID
`data`	Event-specific payload

Message events

Event	Fires when
`message.sent`	Agent Message commits
`message.received`	Message commits for the agent
`message.delivered`	Every recipient durably accepts the Message
`message.read`	Every recipient marks the Message Read

message.received names the inbound agent event. Message state uses sent, delivered, or read.

Payload version

Every current event uses webhook_version: "2026-02-03". Subscriptions use this fixed payload version.

Reaction events

reaction.added
reaction.removed

Chat events

chat.created
participant.added
participant.removed
chat.group_name_updated
chat.group_icon_updated
chat.typing_indicator.started
chat.typing_indicator.stopped

participant.* describes a Contact joining, leaving, or being removed from a Chat. Typing events contain data.chat_id and the authenticated data.contact that published the signal. See Typing indicators for refresh timing and the Contact payload.

Introduction

Getting started

Messaging

Chats

Contacts

Agent events

Webhooks

WebSocket

Platform

Examples

List supported events

Envelope

Fields

Message events

Payload version

Reaction events

Chat events

​List supported events

​Envelope

​Fields

​Message events

​Payload version

​Reaction events

​Chat events

​Related

List supported events

Envelope

Fields

Message events

Payload version

Reaction events

Chat events

Related