Webhooks

Register a receiver

curl -sS -X POST "https://api.relayapp.im/v1/webhooks" \
  -H "Authorization: Bearer $RELAY_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://agent.example/webhooks/relay",
    "events": ["message.received", "reaction.added", "reaction.removed"]
  }'

{
  "webhook": {
    "id": "wh_01m135ve2e5h5hw84f013eym3j",
    "url": "https://agent.example/webhooks/relay",
    "events": ["message.received", "reaction.added", "reaction.removed"],
    "enabled": true,
    "secret_prefix": "whsec_abcd",
    "disabled_at": null,
    "last_disabled_reason": null,
    "created_at": "2026-08-27T18:00:00.000Z",
    "updated_at": "2026-08-27T18:00:00.000Z"
  },
  "signing_secret": "whsec_EXAMPLEKEYDONOTUSE0000000000000000"
}

Rule	Behavior
Receiver URL	Public HTTPS in staging and production. Credentials and fragments are rejected
Signing secret	Returned only when created or rotated. Store it in a secret manager
Subscriptions	Up to five enabled receivers per agent
Event filter	A non-empty subset of the supported Linq event names

Receive the Linq envelope

Relay sends Linq’s current v3 webhook shape directly. Relay’s prefixed IDs are the field values because Relay owns those records, but the field names and nesting follow Linq.

{
  "api_version": "v3",
  "webhook_version": "2026-02-03",
  "event_type": "message.received",
  "event_id": "evt_01m135vfepewek1yqy3p82yszs",
  "created_at": "2026-08-27T18:06:02.000Z",
  "trace_id": "8af9171a45022df2eb74ba4e4c83be0f",
  "partner_id": "agt_01jz9x4t2snbqe6m8v3kcyh7wd",
  "data": {
    "chat": {
      "id": "cnv_01jz9x4t3af8rjq2w6y5nkd0vh",
      "is_group": false,
      "owner_handle": {
        "id": "agt_01jz9x4t2snbqe6m8v3kcyh7wd",
        "handle": "relay",
        "is_me": true,
        "service": "iMessage",
        "status": "active",
        "joined_at": "2026-08-27T18:00:00.000Z",
        "left_at": null
      },
      "health_status": {
        "status": "HEALTHY",
        "doc_url": "https://docs.linqapp.com/guides/chats/chat-health#healthy",
        "updated_at": "2026-08-27T18:06:02.000Z"
      }
    },
    "id": "msg_01jz9xa2tqe8vh5k2wy7ncd4rb",
    "direction": "inbound",
    "sender_handle": {
      "id": "usr_01jz8w2k5qnd7vh3e9tcyf4mrb",
      "handle": "morrison",
      "is_me": false,
      "service": "iMessage",
      "status": "active",
      "joined_at": "2026-08-27T18:00:00.000Z",
      "left_at": null
    },
    "parts": [{ "type": "text", "value": "Move standup to 10" }],
    "effect": null,
    "reply_to": null,
    "sent_at": "2026-08-27T18:06:02.000Z",
    "delivered_at": null,
    "read_at": null,
    "service": "iMessage"
  }
}

See Event types for each event-specific data object.

Verify every request

Relay uses the same Standard Webhooks headers Linq documents:

Header	Value
`webhook-id`	The stable `event_id` and deduplication key
`webhook-timestamp`	Unix seconds when this attempt was signed
`webhook-signature`	One or more space-separated `v1,<base64>` signatures

Compute HMAC-SHA256 over the exact UTF-8 value:

webhook-id.webhook-timestamp.raw-request-body

Decode the base64 value after whsec_ before using it as the HMAC key. Verify the raw bytes before JSON parsing, reject timestamps more than five minutes old, and compare signatures in constant time.

npm install standardwebhooks

import { Webhook } from "standardwebhooks";

const rawBody = await request.text();
const event = new Webhook(env.RELAY_WEBHOOK_SECRET).verify(rawBody, {
  "webhook-id": request.headers.get("webhook-id") ?? "",
  "webhook-timestamp": request.headers.get("webhook-timestamp") ?? "",
  "webhook-signature": request.headers.get("webhook-signature") ?? "",
});

Acknowledge before processing

Persist the verified event and return any 2xx within 10 seconds. Run model and tool work after the acknowledgement. A successful message.received delivery advances the agent’s delivered watermark. Delivery is at least once. Store webhook-id as a unique key, return 2xx without repeating side effects for a duplicate, and derive outbound message IDs from event_id so redelivery cannot create a duplicate reply.

Response	Disposition
Any `2xx`	Success
`408`, `429`, any `5xx`	Retry
Redirect	Dead-letter immediately and never follow
Any other `4xx`	Dead-letter immediately
No HTTP status	Retry as a network failure

Retries use exponential backoff with jitter and dead-letter after 10 attempts.

Manage subscriptions

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

curl -sS -X PATCH "https://api.relayapp.im/v1/webhooks/$WEBHOOK_ID" \
  -H "Authorization: Bearer $RELAY_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true, "events": ["message.received"]}'

curl -sS -X POST "https://api.relayapp.im/v1/webhooks/$WEBHOOK_ID/rotate-secret" \
  -H "Authorization: Bearer $RELAY_AGENT_TOKEN"

curl -sS -X DELETE "https://api.relayapp.im/v1/webhooks/$WEBHOOK_ID" \
  -H "Authorization: Bearer $RELAY_AGENT_TOKEN"

Deleting or disabling the last subscription stops external event delivery. There is no second Relay event-delivery protocol to switch to.

Supported events

Event	Fires when
`message.sent`	The agent’s outbound message was committed
`message.received`	A participant sent an inbound message
`message.delivered`	An outbound message reached its recipient
`message.read`	An outbound message was read
`reaction.added` / `reaction.removed`	A reaction was added or removed
`chat.created`	A conversation was created
`chat.group_name_updated` / `chat.group_icon_updated`	Group metadata changed
`participant.added` / `participant.removed`	Group membership changed

Ignore unknown event types so adding a Linq event does not break your handler.

Start here

Send

Receive

Connect what you already run

Reference

Relay for Business

About Relay

Register a receiver

Receive the Linq envelope

Verify every request

Acknowledge before processing

Manage subscriptions

Supported events

Next steps

​Register a receiver

​Receive the Linq envelope

​Verify every request

​Acknowledge before processing

​Manage subscriptions

​Supported events

​Next steps

Register a receiver

Receive the Linq envelope

Verify every request

Acknowledge before processing

Manage subscriptions

Supported events

Next steps