> ## 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

> Configurar webhooks e consultar logs de entrega com o SDK PHP

Use `$vzaps->webhooks()` para receber eventos da VZaps via HTTP callback na sua aplicação.

Campos comuns em todas as chamadas:

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

## `webhooks()->get($instanceId, $instanceToken = null)`

Lê a configuração atual do webhook.

```php theme={null}
$webhook = $vzaps->webhooks()->get('VZ...', 'instance-token');

print_r($webhook);
```

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

## `webhooks()->set($request)`

Define URL e eventos assinados.

```php theme={null}
$vzaps->webhooks()->set([
    'instanceId' => 'VZ...',
    'instanceToken' => 'instance-token',
    'webhookURL' => '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                              |
| ------------ | ---------------------- | ----------- | -------------------------------------- |
| `webhookURL` | `string`               | Sim         | URL pública que receberá os callbacks. |
| `events`     | `string[]` ou `string` | Não         | Eventos assinados.                     |

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

## `webhooks()->searchLogs($request)`

Busca logs de entrega do webhook.

```php theme={null}
$logs = $vzaps->webhooks()->searchLogs([
    'instanceId' => 'VZ...',
    'instanceToken' => 'instance-token',
    'status' => 'failed',
]);

print_r($logs);
```

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

## `webhooks()->getLog($request)`

Lê um log específico de entrega.

```php theme={null}
$log = $vzaps->webhooks()->getLog([
    'instanceId' => 'VZ...',
    'instanceToken' => 'instance-token',
    'logId' => 'log_123',
]);

print_r($log);
```

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

## `webhooks()->retryLog($request)`

Reenvia uma entrega com falha.

```php theme={null}
$vzaps->webhooks()->retryLog([
    'instanceId' => 'VZ...',
    'instanceToken' => 'instance-token',
    'logId' => 'log_123',
]);
```

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

## Quando usar webhook

Use webhook quando:

* sua aplicação já possui URL pública para receber callbacks;
* você quer processar eventos de forma assíncrona 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 URL, prefira [Realtime](/pt-BR/sdk/php/realtime).