Webhooks - VZaps Docs

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.

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.

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.

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.

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.

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.

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

​client.webhooks.set(...)

​client.webhooks.search_logs(...)

​client.webhooks.get_log(...)

​client.webhooks.retry_log(...)

​Quando usar webhooks