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

Use `$vzaps->webhooks()` to receive VZaps events through HTTP callbacks in your application.

Common fields on all calls:

| Field           | Type     | Required | Description     |
| --------------- | -------- | -------- | --------------- |
| `instanceId`    | `string` | Yes      | Instance ID.    |
| `instanceToken` | `string` | Yes      | Instance token. |

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

Reads the current webhook configuration.

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

print_r($webhook);
```

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

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

Sets the URL and subscribed events.

```php theme={null}
$vzaps->webhooks()->set([
    'instanceId' => 'VZ...',
    'instanceToken' => 'instance-token',
    'webhookURL' => 'https://example.com/webhooks/vzaps',
    'events' => ['Message', 'ReadReceipt', 'Connected', 'Disconnected'],
]);
```

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

| Field        | Type                   | Required | Description                             |
| ------------ | ---------------------- | -------- | --------------------------------------- |
| `webhookURL` | `string`               | Yes      | Public URL that will receive callbacks. |
| `events`     | `string[]` or `string` | No       | Subscribed events.                      |

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

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

Searches webhook delivery logs.

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

print_r($logs);
```

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

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

Reads one delivery log.

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

print_r($log);
```

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

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

Retries a failed delivery.

```php theme={null}
$vzaps->webhooks()->retryLog([
    'instanceId' => 'VZ...',
    'instanceToken' => 'instance-token',
    'logId' => '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 your 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/php/realtime).