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

# List webhooks

`GET /v1/webhooks`

## Request

- Base URL: `https://cherami.to`
- URL: `https://cherami.to/v1/webhooks`
- Auth: HTTP bearer

Lists the account's webhooks with their URL, event types, inbox scope and `status`. Secrets aren't listed: [retrieve one](https://cherami.to/docs/api/webhooks/get-webhook-secret) when you need it. [Receive webhook notifications](https://cherami.to/docs/guides/webhooks)

## Response `200`

Success.

- WebhookList
  - `webhooks` Webhook[], required
    - `id` string, required: Cherami resource ID.
    - `created_at` string, date-time, required: UTC timestamp with milliseconds.
    - `url` string, nullable, required: Destination URL; null while status is pending or unknown.
    - `event_types` WebhookEventType[], nullable, required
    - `inbox_ids` string[], nullable, required: Scoped inboxes; empty means every inbox.
    - `deleted_inbox_ids` string[], required: Scoped inboxes that have since been deleted. They match nothing; edit inbox_ids to remove them.
    - `enabled` boolean, nullable, required
    - `updated_at` string, date-time, nullable, required: UTC timestamp with milliseconds.
    - `status` 'active' | 'disabled' | 'pending' | 'unknown', required
    - `pending_operation` object, nullable, required
      - `kind` 'create' | 'delete' | 'rotate', required
      - `started_at` string, date-time, required: UTC timestamp with milliseconds.
    - `secret_rotated_at` string, date-time, nullable, required: UTC timestamp with milliseconds.
    - `previous_secret_expires_at` string, date-time, nullable, required: UTC timestamp with milliseconds.

## Other responses

- `401`: `unauthorized`: Send a valid API key as `Authorization: Bearer <key>`. If the key stopped working, get a new one through [recovery](https://cherami.to/docs/guides/recovery).
- `503`: `webhooks_unavailable`: Webhook management failed. If it was a change, it may have been applied: list or read the webhooks before repeating it.

---

[API](https://skmtc.dev/cherami/apis/cherami-http-api.md) · [All operations](https://skmtc.dev/cherami/apis/cherami-http-api/llms.txt) · [OpenAPI document](https://skmtc.dev/cherami/apis/cherami-http-api/revisions/7bd993d538af?raw)