Webhooks - VZaps Docs

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.

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.

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.

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.

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.

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.

​client.webhooks.get(instance_id, instance_token=...)

​client.webhooks.set(...)

​client.webhooks.search_logs(...)

​client.webhooks.get_log(...)

​client.webhooks.retry_log(...)

​When to use webhooks