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

# List Webhook Endpoints — GET /webhooks | ByDoctor API

> Retrieve all registered webhook endpoints for your clinic, including subscribed event types and active status. The signing secret is never returned.

The **List Webhook Endpoints** endpoint returns every webhook you have registered for your clinic, along with the event types each endpoint subscribes to and its current active state. Use this endpoint to audit your integrations, verify subscriptions, or build a management UI over your webhook configuration.

## Endpoint

```
GET https://api.bydoctor.com.br/v1/webhooks
```

## Authentication

Include your API key as a Bearer token in the `Authorization` header of every request.

```
Authorization: Bearer YOUR_API_KEY
```

## Query Parameters

<ParamField query="limit" type="integer" default="20">
  Number of webhook records to return per page. Maximum value is `100`.
</ParamField>

<ParamField query="cursor" type="string">
  Pagination cursor returned in the previous response's `meta.next_cursor`. Omit this parameter to start from the first page.
</ParamField>

## Response Fields

<ResponseField name="data" type="array">
  Array of webhook endpoint objects registered to your clinic.

  <Expandable title="Webhook object fields">
    <ResponseField name="id" type="string">
      Unique identifier for the webhook endpoint (UUID).
    </ResponseField>

    <ResponseField name="clinic_id" type="string">
      Identifier of the clinic that owns this webhook.
    </ResponseField>

    <ResponseField name="url" type="string">
      The HTTPS URL where ByDoctor delivers event payloads.
    </ResponseField>

    <ResponseField name="events" type="array">
      List of event names this endpoint is subscribed to (e.g. `["appointment.created", "payment.paid"]`).
    </ResponseField>

    <ResponseField name="active" type="boolean">
      `true` if the endpoint is active and will receive event deliveries. `false` if the endpoint has been paused.
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 UTC timestamp of when this webhook was registered.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta" type="object">
  Pagination metadata for the current result set.

  <Expandable title="Meta fields">
    <ResponseField name="meta.total" type="integer">
      Total number of webhook endpoints registered for your clinic.
    </ResponseField>

    <ResponseField name="meta.has_more" type="boolean">
      `true` if there are additional pages beyond the current one.
    </ResponseField>

    <ResponseField name="meta.next_cursor" type="string">
      Cursor to pass as the `cursor` query parameter to fetch the next page. `null` when `has_more` is `false`.
    </ResponseField>
  </Expandable>
</ResponseField>

<Note>
  The `secret` field is **never returned** when listing webhooks. It is only included in the response when you first create the endpoint via `POST /webhooks`. If you lose your secret, you will need to delete the existing webhook and create a new one to receive a fresh signing secret.
</Note>

## Error Responses

| Status             | Code           | Description                         |
| ------------------ | -------------- | ----------------------------------- |
| `401 Unauthorized` | `unauthorized` | Your API key is missing or invalid. |

## Example Request

```bash theme={null}
curl --request GET \
  --url "https://api.bydoctor.com.br/v1/webhooks" \
  --header "Authorization: Bearer YOUR_API_KEY"
```

## Example Response

```json theme={null}
{
  "data": [
    {
      "id": "wh_c1d2e3f4-a5b6-7890-cdef-123456789abc",
      "clinic_id": "clinic_01HXYZ",
      "url": "https://app.example.com/webhooks/bydoctor",
      "events": [
        "appointment.created",
        "appointment.confirmed",
        "appointment.cancelled",
        "payment.paid"
      ],
      "active": true,
      "created_at": "2024-05-10T08:30:00Z"
    },
    {
      "id": "wh_d2e3f4a5-b6c7-8901-defa-23456789abcd",
      "clinic_id": "clinic_01HXYZ",
      "url": "https://reporting.example.com/hooks/payments",
      "events": [
        "payment.created",
        "payment.paid",
        "payment.cancelled"
      ],
      "active": false,
      "created_at": "2024-03-22T11:15:44Z"
    }
  ],
  "meta": {
    "total": 2,
    "has_more": false,
    "next_cursor": null
  }
}
```