Skip to main content

Subscribe to an event webhook

POST 
/webhook.subscribe

Create or update a webhook subscription for a given event. If a subscription already exists for the same event and URL, its filter is updated instead of creating a duplicate. Re-subscribing the same event and URL also clears a pause (disabledAt / failStreakStartedAt) so deliveries resume on the next event. See Subscription health.

Event names are dotted: chat.message, lobby.booked, magicast.created. Colon names (chat:message:dm, lobby:booked) are v0-only — sending them here returns 400 / Unrecognized event.

Roam does not probe the destination URL when you subscribe — the subscription is created immediately and the first delivery is a real event.

Optional filter limits which occurrences are delivered. Which keys are valid depends on event — see that event's page and the Event Filters table. Omit filter to receive every occurrence. An empty object ({}) is rejected, as is a filter that does not apply to the event.

DMs only:

{
  "url": "https://example.com/hooks/messages",
  "event": "chat.message",
  "filter": { "chatType": "dm" }
}

Required scope: webhook:write

OpenAPI Spec: webhooks-v1.json

Request​

Responses​

Subscription created or updated.