## List webhooks

**get** `/v2/webhooks`

Returns a list of webhooks in your organization using cursor-based pagination.

### Query Parameters

- `limit` - Number of webhooks to return (1-100, default 10)
- `cursor` - Cursor from previous response for pagination
- `status` - Filter by status: "active", "paused", or "suspended"

### Response Format

Returns a list object with:

- `object` - Always "list"
- `data` - Array of webhook objects
- `nextCursor` - Cursor for the next page, or null if no more results

### Webhook Object

Each webhook includes:

- `id` - Unique webhook identifier
- `name` - Human-readable webhook name
- `url` - Webhook endpoint URL
- `topics` - Array of subscribed event topics
- `status` - Current status ("active", "paused", "suspended")
- `health` - Health metrics (response times, error counts)
- `createdAt` - Creation timestamp
- `updatedAt` - Last update timestamp

### Example

```json
{
  "object": "list",
  "data": [
    {
      "object": "webhook",
      "id": "507f1f77bcf86cd799439011",
      "name": "Production Webhook",
      "url": "https://example.com/webhooks",
      "topics": ["post.created", "post.updated"],
      "status": "active",
      ...
    }
  ],
  "nextCursor": "eyJpZCI6IjUwN2YxZjc3YmNmODZjZDc5OTQzOTAxMSJ9"
}
```

### Version Availability

This endpoint is only available in API version 2026-01-01.nova and newer.

### Query Parameters

- `cursor: optional string`

  An opaque cursor for pagination. Use the nextCursor value from a previous response to fetch the next page of results.

- `limit: optional number`

  A limit on the number of objects to be returned, between 1 and 100.

- `status: optional "active" or "paused" or "suspended"`

  Filter webhooks by status

  - `"active"`

  - `"paused"`

  - `"suspended"`

### Header Parameters

- `"Featurebase-Version": optional "2026-01-01.nova" or "2025-12-12.clover"`

  - `"2026-01-01.nova"`

  - `"2025-12-12.clover"`

### Returns

- `data: array of Webhook`

  Array of webhooks

  - `id: string`

    Unique identifier

  - `createdAt: string`

    ISO timestamp when the webhook was created

  - `description: string`

    Optional description of the webhook purpose

  - `health: object { avgResponseTime, consecutiveFailures, errorsSinceLastSuccess, 2 more }`

    - `avgResponseTime: number`

      Average response time in milliseconds

    - `consecutiveFailures: number`

      Number of consecutive delivery failures

    - `errorsSinceLastSuccess: number`

      Number of errors since last successful delivery

    - `lastResponseTime: number`

      Last response time in milliseconds

    - `lastSuccessAt: string`

      ISO timestamp of last successful delivery

  - `lastStatus: object { code, message, timestamp }`

    Last delivery attempt status

    - `code: number`

      HTTP status code from last delivery attempt

    - `message: string`

      Status message from last delivery attempt

    - `timestamp: string`

      ISO timestamp of last status update

  - `name: string`

    Human-readable webhook name

  - `object: "webhook"`

    Object type identifier

    - `"webhook"`

  - `requestConfig: object { timeoutMs, headers }`

    - `timeoutMs: number`

      Request timeout in milliseconds (1000-30000)

    - `headers: optional map[string]`

      Custom headers to send with webhook requests

  - `secret: string`

    Webhook signing secret for verifying payloads

  - `status: "active" or "paused" or "suspended"`

    Current status of the webhook

    - `"active"`

    - `"paused"`

    - `"suspended"`

  - `topics: array of "post.created" or "post.updated" or "post.deleted" or 24 more`

    Array of event topics the webhook subscribes to

    - `"post.created"`

    - `"post.updated"`

    - `"post.deleted"`

    - `"post.voted"`

    - `"ticket.created"`

    - `"ticket.updated"`

    - `"ticket.deleted"`

    - `"changelog.published"`

    - `"comment.created"`

    - `"comment.updated"`

    - `"comment.deleted"`

    - `"conversation.user.created"`

    - `"conversation.user.replied"`

    - `"conversation.admin.replied"`

    - `"conversation.admin.closed"`

    - `"conversation.handover_requested"`

    - `"conversation.admin.assigned"`

    - `"conversation.admin.noted"`

    - `"conversation.admin.snoozed"`

    - `"conversation.admin.unsnoozed"`

    - `"conversation.admin.opened"`

    - `"conversation.priority.updated"`

    - `"conversation.deleted"`

    - `"conversation.contact.attached"`

    - `"conversation.contact.detached"`

    - `"conversation.read"`

    - `"conversation_part.redacted"`

  - `updatedAt: string`

    ISO timestamp when the webhook was last updated

  - `url: string`

    Webhook endpoint URL

  - `version: string`

    API version for webhook payloads

- `nextCursor: string`

  Cursor for fetching the next page (cursor-based pagination)

- `object: "list"`

  Object type identifier

  - `"list"`

### Example

```http
curl https://do.featurebase.app/v2/webhooks \
    -H "Authorization: Bearer $FEATUREBASE_API_KEY"
```

#### Response

```json
{
  "data": [
    {
      "id": "507f1f77bcf86cd799439011",
      "createdAt": "2025-01-15T10:30:00.000Z",
      "description": "Handles all production events",
      "health": {
        "avgResponseTime": 200,
        "consecutiveFailures": 0,
        "errorsSinceLastSuccess": 0,
        "lastResponseTime": 150,
        "lastSuccessAt": "2025-01-15T10:30:00.000Z"
      },
      "lastStatus": {
        "code": 200,
        "message": "Success",
        "timestamp": "2025-01-15T10:30:00.000Z"
      },
      "name": "Production Webhook",
      "object": "webhook",
      "requestConfig": {
        "timeoutMs": 5000,
        "headers": {
          "X-Custom-Header": "value"
        }
      },
      "secret": "whsec_abc123def456ghi789",
      "status": "active",
      "topics": [
        "post.created",
        "post.updated"
      ],
      "updatedAt": "2025-01-15T10:30:00.000Z",
      "url": "https://example.com/webhooks",
      "version": "1.0"
    }
  ],
  "nextCursor": "eyJpZCI6IjUwN2YxZjc3YmNmODZjZDc5OTQzOTAxMSJ9",
  "object": "list"
}
```