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

# List Webhooks

Lists all webhook configurations for your API key.

## Overview

The list webhooks endpoint returns all webhook configurations associated with your API key. Use this to monitor webhook health, check subscription status, and manage your webhook configurations.

## Authentication

<ParamField header="Authorization" type="string" required>
  Bearer token with `read:webhooks` scope
</ParamField>

## Query Parameters

<ParamField query="companyId" type="string">
  Filter webhooks by company ID. If provided, returns only webhooks associated with that specific company (excludes global webhooks). If omitted, returns all webhooks including global ones. Useful for ATS integrations managing multiple companies.
</ParamField>

## Response

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

<ResponseField name="total" type="number">
  Total number of webhook configurations
</ResponseField>

### Webhook Configuration Object

<ResponseField name="id" type="string">
  Unique identifier for the webhook
</ResponseField>

<ResponseField name="apiKeyId" type="string">
  The API key ID this webhook belongs to
</ResponseField>

<ResponseField name="companyId" type="string">
  Company ID this webhook is associated with. Null if webhook receives events for all companies (global webhook).
</ResponseField>

<ResponseField name="url" type="string">
  The endpoint URL receiving webhook notifications
</ResponseField>

<ResponseField name="name" type="string">
  Human-readable name for the webhook
</ResponseField>

<ResponseField name="description" type="string">
  Description of the webhook's purpose
</ResponseField>

<ResponseField name="headers" type="array">
  Custom headers configured for this webhook. Sensitive header values are
  masked.
</ResponseField>

<ResponseField name="events" type="array">
  Array of subscribed event type labels (e.g., "interview\.completed")
</ResponseField>

<ResponseField name="isActive" type="boolean">
  Whether the webhook is currently active
</ResponseField>

<ResponseField name="maxRetries" type="number">
  Maximum retry attempts for failed deliveries
</ResponseField>

<ResponseField name="timeoutMs" type="number">
  Request timeout in milliseconds
</ResponseField>

<ResponseField name="consecutiveFailures" type="number">
  Current count of consecutive delivery failures
</ResponseField>

<ResponseField name="circuitOpenedAt" type="string">
  ISO 8601 timestamp when circuit breaker was triggered (null if closed)
</ResponseField>

<ResponseField name="createdAt" type="string">
  ISO 8601 timestamp when webhook was created
</ResponseField>

<ResponseField name="updatedAt" type="string">
  ISO 8601 timestamp when webhook was last updated
</ResponseField>

## Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.instaview.sk/webhooks?companyId=company-uuid" \
    -H "Authorization: Bearer sk_your_key_here"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.instaview.sk/webhooks", {
    headers: {
      Authorization: `Bearer ${process.env.INSTAVIEW_API_KEY}`,
    },
  });

  const { data } = await response.json();
  console.log(`Found ${data.total} webhooks`);
  ```

  ```python Python theme={null}
  response = requests.get(
      'https://api.instaview.sk/webhooks',
      headers={
          'Authorization': f'Bearer {os.environ["INSTAVIEW_API_KEY"]}'
      }
  )

  data = response.json()['data']
  print(f'Found {data["total"]} webhooks')
  ```
</CodeGroup>

## Example Response

```json theme={null}
{
  "success": true,
  "data": {
    "data": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "apiKeyId": "api-key-uuid",
        "companyId": "company-uuid",
        "url": "https://api.example.com/webhooks/instaview",
        "name": "Production Webhook",
        "description": "Receives interview completion notifications",
        "headers": [
          { "name": "Authorization", "isMasked": true },
          { "name": "X-Custom-Header", "isMasked": false }
        ],
        "events": ["interview.completed", "analysis.completed"],
        "isActive": true,
        "maxRetries": 3,
        "timeoutMs": 30000,
        "consecutiveFailures": 0,
        "circuitOpenedAt": null,
        "createdAt": "2024-01-15T10:30:00Z",
        "updatedAt": "2024-01-15T10:30:00Z"
      }
    ],
    "total": 1
  }
}
```

## Monitoring Webhook Health

Check webhook health by examining `consecutiveFailures` and `circuitOpenedAt`:

```javascript theme={null}
async function checkWebhookHealth() {
  const response = await fetch("https://api.instaview.sk/webhooks", {
    headers: { Authorization: `Bearer ${apiKey}` },
  });

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

  const unhealthy = data.data.filter(
    (w) => w.consecutiveFailures > 0 || w.circuitOpenedAt
  );

  for (const webhook of unhealthy) {
    console.warn(`Webhook ${webhook.name || webhook.id}:`);
    console.warn(`  Failures: ${webhook.consecutiveFailures}`);
    console.warn(`  Circuit Open: ${webhook.circuitOpenedAt || "No"}`);
  }

  return unhealthy;
}
```

## Related

<CardGroup cols={2}>
  <Card title="Create Webhook" icon="plus" href="/api-reference/webhooks/create-webhook">
    Create a new webhook configuration
  </Card>

  <Card title="Webhooks Guide" icon="webhook" href="/guides/webhooks">
    Learn about webhook events and payloads
  </Card>
</CardGroup>