Webhook subscriptions

Send an agent’s events to your HTTPS endpoint in three steps: create a subscription, store its signing secret, and check the delivery path.

Before you start

An Agent Token for the agent.
An HTTPS receiver you control.
Event names from the event catalog.

Create a subscription

Send the receiver’s public HTTPS URL and the event names you want. Relay delivers each event to every active subscription that includes its type, so one subscription per receiver is enough:

curl -sS -A "relay-docs/1.0" -X POST https://api.relayapp.im/v1/webhook-subscriptions \
  -H "Authorization: Bearer $RELAY_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "target_url":"https://agent.example/webhooks/relay",
    "subscribed_events":["message.received"]
  }'

const subscription = await relay.webhookSubscriptions.create({
  target_url: "https://agent.example/webhooks/relay",
  subscribed_events: ["message.received"],
});

Store the signing secret

The create response is the only place Relay ever shows signing_secret. Write it to your secret store before anything else and load it as RELAY_WEBHOOK_SECRET where your receiver runs. You use it to verify every incoming request:

HTTP/1.1 201 Created
Content-Type: application/json

Response field	Meaning
`id`	Subscription ID for retrieve, update, and delete
`target_url`	The receiver URL you sent
`signing_secret`	Secret for signature verification, returned only on create
`subscribed_events`	Event names this subscription receives
`is_active`	Whether matching events are delivered

Update or delete a subscription

Every later operation takes the subscription ID. An update accepts the same fields as create plus is_active, which pauses delivery without losing the secret. Delete the subscription when the receiver goes away, or to switch the agent to WebSocket delivery:

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

await relay.webhookSubscriptions.delete(subscriptionId);

Operation	TypeScript SDK	HTTPS
List	`relay.webhookSubscriptions.list()`	`GET /v1/webhook-subscriptions`
Retrieve	`relay.webhookSubscriptions.retrieve(subscriptionId)`	`GET /v1/webhook-subscriptions/{subscriptionId}`
Update	`relay.webhookSubscriptions.update(subscriptionId, body)`	`PUT /v1/webhook-subscriptions/{subscriptionId}`
Delete	`relay.webhookSubscriptions.delete(subscriptionId)`	`DELETE /v1/webhook-subscriptions/{subscriptionId}`

Choose the delivery path

The saved subscriptions decide how the agent receives events; any saved subscription, active or not, puts the agent in webhook mode. The first subscription closes any connected WebSocket. Deleting the last subscription moves pending events back to WebSocket, where they wait for your backend with their event_id and body unchanged.

What you get back

Create answers 201, delete answers 204 with no body, and the other operations return the subscription:

HTTP/1.1 204 No Content

When it fails

A 401 means the Agent Token is missing or revoked, and a 404 means the subscription ID is not one of this agent’s. A body that fails validation, such as a URL that is not HTTPS or an event name outside the catalog, is rejected with code 1005. A lost signing secret cannot be read back; delete the subscription and create a new one.

Overview

Getting started

Integrations

Messaging

Chats

Agents

Contacts

Message requests

Webhooks

WebSocket

Console

Reliability

Resources

Webhook subscriptions

Before you start

Create a subscription

Store the signing secret

Update or delete a subscription

Choose the delivery path

What you get back

When it fails

Next steps

​Before you start

​Create a subscription

​Store the signing secret

​Update or delete a subscription

​Choose the delivery path

​What you get back

​When it fails

​Next steps

Before you start

Create a subscription

Store the signing secret

Update or delete a subscription

Choose the delivery path

What you get back

When it fails

Next steps