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

# List Webhooks

> List webhook subscriptions.

List webhook subscriptions visible to the authenticated credential owner.

### Endpoint

`POST /v3/webhooks/list`

### Authentication and target

Access is resolved through the authenticated credential owner. Account credentials can target only their own account. User credentials must supply `account_number` for transaction events and omit it for VA Account KYB. Platform credentials can manage only Master Account KYB and must omit `account_number`. See **Webhook Management** for the complete event/owner matrix.

Do not send X-ISPB or X-Account-Number with a platform or user credential. An account credential may omit both headers; if sent, both are required and must match its bound account.

### Request body

| Field             | Required    | Description                                            |
| ----------------- | ----------- | ------------------------------------------------------ |
| `event_type`      | No          | Event filter. Omit it to list the allowed owner scope. |
| `account_number`  | Conditional | Required or forbidden by the owner/event policy.       |
| `subscription_id` | No          | Present in the contract but currently ignored by List. |

### Success data

`webhooks[]`; each item contains `webhook_id`, `event_type`, `callback_url`, `status`, `created_at`, and `updated_at`.

### Behavior and validation

This endpoint is not paginated. Account-scoped list explicitly asks for active configurations; do not assume identical filtering for every other owner scope.

### Errors

Every call can fail for missing or invalid signature headers, an expired timestamp, nonce replay, an invalid body hash or signature, insufficient permission, or a downstream service error. Endpoint-specific errors include:

* `permission_denied` for a disallowed owner/event/account combination.

### Example request

```bash theme={null}
curl --request POST "${BASE_URL}/v3/webhooks/list" \
  --header "Content-Type: application/json" \
  --header "X-Client-ID: ${CLIENT_ID}" \
  --header "X-Timestamp: ${TIMESTAMP_MS}" \
  --header "X-Nonce: ${NONCE}" \
  --header "X-Signature: ${SIGNATURE}" \
  --data '{"event_type":5}'
```

### Example response

```json theme={null}
{"code":200,"message":"success","data":{"webhooks":[{"webhook_id":"wh_demo_002","event_type":"VA_ACCOUNT_KYB","callback_url":"https://webhook.example.test/kyb","status":1}]},"time":1710000400000}
```