---
title: "List webhooks"
method: GET
path: "/v2/webhooks"
tags: ["Webhooks"]
---

# List webhooks

`GET /v2/webhooks`

## Request

- Base URL: `https://api.village.ai`
- URL: `https://api.village.ai/v2/webhooks`
- Auth: HTTP bearer

List the webhook endpoints registered on this account. Use this to show the user where Village is currently sending their data, to find a webhook's id before updating or deleting it, or to check whether one is paused. Each entry gives the delivery url, the event_filter it listens to (null means every event type), is_active, and has_secret. Supports pagination (cursor, limit), filtering by is_active, and a substring search over url and description. The HMAC signing secret is never returned.

## Query parameters

- `cursor` string: Opaque cursor for pagination (from the previous response)
- `limit` string: Number of webhooks per page (max 100)
- `is_active` 'true' | 'false': Filter by active state. Omit to return both active and paused webhooks.
- `search` string: Substring match against the webhook URL or description

## Response `200`

Webhooks retrieved successfully

- object
  - `data` Webhook[], required: Page of webhooks owned by the caller
    - `id` string, required: Encrypted webhook identifier
    - `url` string, required: Endpoint that receives event payloads
    - `description` string, nullable, required: Human-readable label, or null if none was set
    - `is_active` boolean, required: True when the webhook is receiving deliveries; false when paused
    - `event_filter` string[], nullable, required: Event types delivered to this webhook. NULL means every event type is delivered.
    - `has_secret` boolean, required: Whether an HMAC signing secret is configured. The secret value is write-only — it is returned once by create_webhook and never again, so reads report only this flag.
    - `created_at` string, required: ISO 8601 creation timestamp
    - `updated_at` string, required: ISO 8601 last update timestamp
  - `metadata` object, required
    - `request_id` string, required
  - `pagination` PaginationInfo, required: Cursor-based pagination metadata
    - `cursor` string, nullable, required: Opaque cursor for fetching the next page (null if no more results)
    - `has_next_page` boolean, required: Whether more results are available
    - `count` integer, required: Total number of results or count of items in current page

## Other responses

- `400`: Bad request - invalid parameters
- `401`: Unauthorized - missing or invalid authentication

---

[API](https://skmtc.dev/village/apis/village-v2-api.md) - [All operations](https://skmtc.dev/village/apis/village-v2-api/llms.txt) - [OpenAPI document](https://skmtc.dev/village/apis/village-v2-api/revisions/aebe21a1a544?raw)