# List webhook subscriptions

`GET /webhook.list`

## Description

List all webhook subscriptions owned by the authenticated API client.

The response includes both **dynamic** subscriptions (created via
[`/webhook.subscribe`](/docs/webhooks/webhook-subscribe)) and **static**
subscriptions configured in the Roam Administration UI.

Each object may include `lastSuccessAt`, `failStreakStartedAt`, and
`disabledAt` (omitted when null). `disabledAt` means the destination is
paused. See [Subscription health](/docs/webhooks/webhooks#subscription-health).

**Required scope:** `webhook:read`

---

**OpenAPI Spec:** [webhooks-v1.json](https://developer.ro.am/webhooks-v1.json)

## Authentication

```
Authorization: Bearer YOUR_API_KEY
```

## Responses

### 200 - List of webhook subscriptions.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `webhooks` | object[] | Yes | Webhook subscriptions owned by this API client. Empty array if none exist. |

**webhooks** (array item):

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `id` | string | Yes | Unique identifier of the webhook subscription. |
| `event` | string | Yes | Subscribed event name (e.g. `chat.message`, `chat.reaction`). |
| `url` | string | Yes | Destination URL for webhook deliveries. |
| `filter` | WebhookSubscriptionFilter | No | Event-specific filter applied to the subscription. Omitted if no filter is set. |
| `dynamic` | boolean | Yes | `true` if the subscription was created via `/webhook.subscribe`. `false` if it was configured statically in the Roam Administration UI.  |
| `created` | string | No | When the subscription was created. |
| `lastSuccessAt` | string | No | Last terminal 2xx (RFC3339 UTC). Omitted until the destination has succeeded at least once.  |
| `failStreakStartedAt` | string | No | Start of the current consecutive-failure span (RFC3339 UTC). Omitted when healthy.  |
| `disabledAt` | string | No | When the fail streak reached 24 hours (RFC3339 UTC). While set the subscription is paused. Omitted when active.  |

**WebhookSubscriptionFilter**:

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `chatType` | "dm" | "group" | No | For `chat.message`: restrict to direct messages (`dm`) or group messages (`group`). |
| `mention` | boolean | No | For `chat.message`: restrict to messages that @mention your app. |
| `names` | string[] | No | For `chat.reaction`: restrict to events where the changed reaction is one of these names (e.g. 'thumbs_up', 'heart'), matching the `name` field of `/reaction.add` and `/reaction.list`. |
| `hasVideo` | "true" | No | For `meeting.ended`: restrict to meetings that were video recorded, i.e. a video track exists. This keys on "was recorded", not "is ready to fetch" — the recording upload is a separate pipeline that h |
| `eventId` | string | No | For On-Air events (`onair.event.*`, `onair.guest.*`): restrict to the specified event. |
| `status` | "invited" | "going" | "maybe" | "notGoing" | No | For `onair.guest.rsvp`: restrict to the specified RSVP status. |


#### Example Response

```json
{
  "webhooks": [
    {
      "id": "19c6401f-6d02-4d8c-87c5-9fc45f02f4b5",
      "event": "chat.message",
      "url": "https://example.com/hooks/messages",
      "filter": {
        "mention": true
      },
      "dynamic": true,
      "created": "2026-03-12T17:42:18Z",
      "lastSuccessAt": "2026-08-17T14:02:11Z"
    },
    {
      "id": "a7f8e3d2-1b5c-4e9f-8d2a-6f0b1c3d4e5f",
      "event": "chat.reaction",
      "url": "https://example.com/hooks/reactions",
      "dynamic": false,
      "created": "2026-01-04T09:13:00Z",
      "lastSuccessAt": "2026-08-15T09:00:00Z",
      "failStreakStartedAt": "2026-08-16T09:00:00Z",
      "disabledAt": "2026-08-17T09:00:00Z"
    }
  ]
}
```

### 401 - Unauthorized. Either the credentials are invalid, or the token is
missing the required `webhook:read` scope.


### 500 - An internal error occurred.

---

*Machine-readable API documentation.*
*Full documentation: https://developer.ro.am/docs/webhooks/webhook-list*