> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ringyo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# List Webhooks

> List all webhook endpoints

## Request

Retrieve a list of all webhook endpoints configured for your account.

### Headers

<ParamField header="Authorization" type="string" required>
  Bearer token for authentication. Format: `Bearer YOUR_API_KEY`
</ParamField>

### Query Parameters

<ParamField query="limit" type="integer" default="20">
  Number of webhooks to return (1-100)
</ParamField>

<ParamField query="cursor" type="string">
  Pagination cursor from a previous response
</ParamField>

<ParamField query="status" type="string">
  Filter by status: `active`, `inactive`, `failing`
</ParamField>

## Response

<ResponseField name="data" type="array">
  Array of webhook objects
</ResponseField>

<ResponseField name="has_more" type="boolean">
  Whether there are more results available
</ResponseField>

<ResponseField name="next_cursor" type="string">
  Cursor for fetching the next page
</ResponseField>

<ResponseField name="total" type="integer">
  Total number of webhooks
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl "https://api.ringyo.ai/v1/webhooks?status=active" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    'https://api.ringyo.ai/v1/webhooks?status=active',
    {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
      },
    }
  );

  const { data } = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://api.ringyo.ai/v1/webhooks',
      headers={'Authorization': 'Bearer YOUR_API_KEY'},
      params={'status': 'active'}
  )

  data = response.json()
  webhooks = data['data']
  ```
</RequestExample>

<ResponseExample>
  ```json 200 - Success theme={null}
  {
    "data": [
      {
        "id": "wh_abc123",
        "url": "https://your-app.com/webhooks/ringyo",
        "events": ["call.completed", "call.recording.ready"],
        "description": "Production webhook",
        "status": "active",
        "last_triggered_at": "2024-01-15T14:22:00Z",
        "created_at": "2024-01-10T08:00:00Z"
      },
      {
        "id": "wh_def456",
        "url": "https://staging.your-app.com/webhooks/ringyo",
        "events": ["*"],
        "description": "Staging - all events",
        "status": "active",
        "last_triggered_at": "2024-01-15T12:00:00Z",
        "created_at": "2024-01-12T10:30:00Z"
      }
    ],
    "has_more": false,
    "next_cursor": null,
    "total": 2
  }
  ```
</ResponseExample>

## Webhook Object

| Field               | Type    | Description                         |
| ------------------- | ------- | ----------------------------------- |
| `id`                | string  | Unique identifier                   |
| `url`               | string  | Webhook endpoint URL                |
| `events`            | array   | Subscribed event types              |
| `description`       | string  | Description of the webhook          |
| `status`            | string  | `active`, `inactive`, or `failing`  |
| `last_triggered_at` | string  | Last time webhook was triggered     |
| `failure_count`     | integer | Consecutive failures (when failing) |
| `created_at`        | string  | ISO 8601 timestamp                  |

## Webhook Status

| Status     | Description                               |
| ---------- | ----------------------------------------- |
| `active`   | Webhook is receiving events normally      |
| `inactive` | Webhook is disabled                       |
| `failing`  | Webhook has consecutive delivery failures |

<Note>
  Webhooks automatically enter `failing` status after 5 consecutive delivery failures.
  They will be automatically disabled after 100 consecutive failures.
</Note>

## Error Codes

| Code             | Description                                       |
| ---------------- | ------------------------------------------------- |
| `invalid_cursor` | The pagination cursor is invalid                  |
| `invalid_status` | Status must be 'active', 'inactive', or 'failing' |