# List Webhooks

Source: https://www.ranked.ai/developers/api-reference/webhooks/list

`GET https://app.ranked.ai/api/v1/webhooks`

> List webhook subscriptions or create a new one

### GET - List subscriptions

Returns all webhook subscriptions for the authenticated user.

- `project_id` (query, string): Filter by project UUID
- `limit` (query, number, default 50): Max subscriptions to return
- `offset` (query, number, default 0): Number to skip

**Request**

```bash cURL
curl "https://app.ranked.ai/api/v1/webhooks" \
  -H "Authorization: Bearer rk_live_your_api_key"
```

### POST - Create subscription

Requires a **Read + Write** API key.

- `name` (body, string): Display name for this subscription
- `url` (body, string, required): Webhook destination URL (must be HTTPS)
- `project_id` (body, string, required): Project UUID to monitor
- `events` (body, string[], required): Events to subscribe to. Options: `content.created`, `content.status_changed`, `audit.started`, `audit.completed`, `keywords.updated`, `prompts.updated`

**Request**

```bash cURL
curl -X POST "https://app.ranked.ai/api/v1/webhooks" \
  -H "Authorization: Bearer rk_live_your_write_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Dashboard",
    "url": "https://your-app.com/webhooks/ranked",
    "project_id": "your-project-uuid",
    "events": ["keywords.updated", "content.status_changed", "audit.completed"]
  }'
```

**Response**

```json 200
{
  "success": true,
  "data": {
    "id": "3a2e02d7-106f-4425-9518-9597dbf5a23a",
    "project_id": "40596405-c27c-4dfc-89e4-142c87846d66",
    "name": "My Dashboard",
    "url": "https://your-app.com/webhooks/ranked",
    "events": ["keywords.updated", "content.status_changed", "audit.completed"],
    "is_active": true,
    "secret": "whsec_daca66d72437cbe7767ec3c3bea5fe359637832f...",
    "created_at": "2026-05-16T01:06:02.042Z"
  }
}
```

> **Warning:** The `secret` is only returned when the subscription is created. Store it securely for signature verification.