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

# Webhooks

> Configure webhooks and inspect delivery logs with the Python SDK

Use `client.webhooks` to receive VZaps events via HTTP callbacks in your application.

Common fields on every call:

| Field            | Type     | Required | Description     |
| ---------------- | -------- | -------- | --------------- |
| `instance_id`    | `string` | Yes      | Instance ID.    |
| `instance_token` | `string` | Yes      | Instance token. |

## `client.webhooks.get(instance_id, instance_token=...)`

Reads the current webhook configuration.

```python theme={null}
webhook = client.webhooks.get("VZ...", instance_token="instance-token")
print(webhook)
```

**Return:** envelope `{ code, success, data }` with `webhook` and `subscribe` (events).

## `client.webhooks.set(...)`

Sets the callback URL and subscribed events.

```python theme={null}
client.webhooks.set(
    instance_id="VZ...",
    instance_token="instance-token",
    webhook_url="https://example.com/webhooks/vzaps",
    events=["Message", "ReadReceipt", "Connected", "Disconnected"],
)
```

**Return:** envelope `{ code, success, data }` with configured `webhook` and `events`.

| Field         | Type                 | Required | Description                         |
| ------------- | -------------------- | -------- | ----------------------------------- |
| `webhook_url` | `string`             | Yes      | Public URL that receives callbacks. |
| `events`      | `list[str]` or `str` | No       | Subscribed events.                  |

Common events: `Message`, `ReadReceipt`, `Connected`, `Disconnected`, `Presence`, `ChatPresence`, `HistorySync`, `GroupParticipantsAdd`, `GroupParticipantsRemove`, `All`.

## `client.webhooks.search_logs(...)`

Searches webhook delivery logs.

```python theme={null}
logs = client.webhooks.search_logs(
    instance_id="VZ...",
    instance_token="instance-token",
    status="failed",
)
print(logs)
```

**Return:** envelope `{ code, success, data }` with paginated logs (`content[]`, totals).

## `client.webhooks.get_log(...)`

Reads one specific delivery log.

```python theme={null}
log = client.webhooks.get_log(
    instance_id="VZ...",
    instance_token="instance-token",
    log_id="log_123",
)
print(log)
```

**Return:** envelope `{ code, success, data }` with one delivery log (status, payload, attempts, etc.).

## `client.webhooks.retry_log(...)`

Retries a failed delivery.

```python theme={null}
client.webhooks.retry_log(
    instance_id="VZ...",
    instance_token="instance-token",
    log_id="log_123",
)
```

**Return:** envelope `{ code, success, data }` confirming callback retry.

## When to use webhooks

Use webhooks when:

* your application already has a public URL for callbacks;
* you want to process events asynchronously in the backend;
* your integration pipeline already works with HTTP POST.

For bots, dashboards, and apps that need low latency without exposing a URL, prefer [Realtime](/en/sdk/python/realtime).