Version: 0.1

Roam HQ Events API (Alpha)

The Roam HQ Events API (Alpha) delivers real-time notifications to your application via webhooks. Subscribe to events and receive HTTP callbacks when things happen in your Roam workspace.

OpenAPI Spec: webhooks.json

Configuring Webhooks

You can configure webhooks in two ways:

• Static: In Roam Administration > Developer > API Client, add webhook URLs directly to your app configuration
• Dynamic: Use the subscription endpoints below to manage webhooks programmatically

Subscription Endpoints

Endpoint	Method	Description
/webhook.subscribe	POST	Create or update a webhook subscription
/webhook.unsubscribe	POST	Remove a webhook subscription

Available Events

Event	Description
chat:message:dm	Direct message received by your app
chat:message:channel	Channel message in a group where your app is a member
chat:message:mention	Message that @mentions your app
chat:message:reaction	Emoji reaction added to a message
recording:saved	Meeting recording is ready for download
transcript:saved	Meeting transcript (Magic Minutes) is available
lobby:booked	New booking created for a lobby
user:status:update	User checked in or out of the Roam
onair.event.created	On-Air event is created
onair.event.updated	On-Air event is updated
onair.event.canceled	On-Air event is canceled
onair.guest.rsvp	Guest RSVP status changed
onair.guest.added	Guest(s) added to an event

Access Models

Webhooks support both Organization access and Personal access. The same events are available in both modes, but the scope differs:

• Organization access: Webhooks deliver events for all activity across the workspace (e.g. all messages in public groups, all meeting transcripts).
• Personal access: Webhooks deliver only events involving the authenticated user (e.g. only your DMs, only your meeting transcripts).

See the Access Models guide for details on choosing the right model.

Webhook Payload Format

All webhooks are delivered as POST requests with JSON payloads. Your endpoint should return a 2xx status to acknowledge receipt.

Signature Verification

Webhooks are signed using the Standard Webhooks specification. Each request includes three headers for verification:

Header	Description
webhook-id	Unique identifier for this webhook delivery
webhook-timestamp	Unix timestamp (seconds) when the webhook was sent
webhook-signature	HMAC-SHA256 signature of the payload

Your Webhook Signing Secret is available in Roam Administration > Developer > API Client.

To verify a webhook:

1. Concatenate: {webhook-id}.{webhook-timestamp}.{payload}
2. Compute HMAC-SHA256 using your signing secret (base64-decoded)
3. Compare with the signature in webhook-signature header

We recommend using the standard-webhooks client libraries for verification:

import { Webhook } from "standardwebhooks";

const wh = new Webhook(signingSecret);
const payload = wh.verify(requestBody, requestHeaders);

Delivery Behavior

• Timeout: Webhook requests timeout after 3 seconds. Ensure your endpoint responds quickly.
• Retries: Webhooks are not automatically retried. If your endpoint returns a non-2xx status or times out, the delivery is logged but not reattempted.
• Order: Webhooks are delivered asynchronously and may arrive out of order.

For reliable processing, we recommend:

• Acknowledge webhooks immediately with a 200 response
• Process webhook data asynchronously in a background job
• Use the webhook-id header for idempotency

Filtering

Some events support filters to limit notifications:

• lobby:booked: Filter by lobbyId to receive bookings for specific lobbies only
• chat:message:reaction: Filter by codes to receive only specific reaction types
• onair.event.created, onair.event.updated, onair.event.canceled, onair.guest.added: Filter by eventId to receive notifications for a specific event only
• onair.guest.rsvp: Filter by eventId and/or status to receive notifications for a specific event or RSVP status

Authentication

Authorization: Bearer YOUR_TOKEN

Base URL

https://api.ro.am/v0

---

Have questions? Contact us via Roam Support Chat or email developer@ro.am.

Contact

Developer Support: developer@ro.am

URL: https://developer.ro.am

Terms of Service

https://ro.am/terms