> ## 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 e inspecione logs de entrega com o SDK Python

Use `client.webhooks` para receber eventos VZaps via callbacks HTTP na sua aplicação.

Campos comuns em todas as chamadas:

| Campo            | Tipo     | Obrigatório | Descrição           |
| ---------------- | -------- | ----------- | ------------------- |
| `instance_id`    | `string` | Sim         | ID da instância.    |
| `instance_token` | `string` | Sim         | Token da instância. |

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

Lê a configuração atual do webhook.

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

**Retorno:** envelope `{ code, success, data }` com `webhook` e `subscribe` (eventos).

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

Define a URL de callback e os eventos inscritos.

```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"],
)
```

**Retorno:** envelope `{ code, success, data }` com `webhook` e `events` configurados.

| Campo         | Tipo                 | Obrigatório | Descrição                            |
| ------------- | -------------------- | ----------- | ------------------------------------ |
| `webhook_url` | `string`             | Sim         | URL pública que recebe os callbacks. |
| `events`      | `list[str]` ou `str` | Não         | Eventos inscritos.                   |

Eventos comuns: `Message`, `ReadReceipt`, `Connected`, `Disconnected`, `Presence`, `ChatPresence`, `HistorySync`, `GroupParticipantsAdd`, `GroupParticipantsRemove`, `All`.

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

Busca logs de entrega do webhook.

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

**Retorno:** envelope `{ code, success, data }` com pagina de logs (`content[]`, totais).

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

Lê um log de entrega específico.

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

**Retorno:** envelope `{ code, success, data }` com um log de entrega (status, payload, tentativas, etc.).

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

Reenvia uma entrega que falhou.

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

**Retorno:** envelope `{ code, success, data }` confirmando reenvio do callback.

## Quando usar webhooks

Use webhooks quando:

* sua aplicação já tem uma URL pública para callbacks;
* você quer processar eventos assincronamente no backend;
* seu pipeline de integração já trabalha com HTTP POST.

Para bots, dashboards e apps que precisam de baixa latência sem expor uma URL, prefira [Realtime](/pt-BR/sdk/python/realtime).