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

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

Campos comuns em toda chamada:

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

## `Webhooks.Get(ctx, instanceID, options)`

Lê a configuração atual do webhook.

```go theme={null}
webhook, err := client.Webhooks.Get(ctx, "VZ...", vzaps.InstanceOptions{
	InstanceToken: "instance-token",
})
fmt.Printf("%#v\n", webhook)
```

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

## `Webhooks.Set(ctx, req)`

Define URL de callback e eventos assinados.

```go theme={null}
_, err := client.Webhooks.Set(ctx, vzaps.WebhookConfigRequest{
	InstanceScopedRequest: vzaps.InstanceScopedRequest{
		InstanceID:    "VZ...",
		InstanceToken: "instance-token",
	},
	WebhookURL: "https://example.com/webhooks/vzaps",
	Events:     []string{"Message", "ReadReceipt", "Connected", "Disconnected"},
})
```

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

| Campo (JSON)  | Campo Go     | Obrigatório | Descrição                         |
| ------------- | ------------ | ----------- | --------------------------------- |
| `webhook_url` | `WebhookURL` | Sim         | URL pública que recebe callbacks. |
| `events`      | `Events`     | Não         | Eventos assinados.                |

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

## `Webhooks.SearchLogs(ctx, req)`

Busca logs de entrega de webhook.

```go theme={null}
logs, err := client.Webhooks.SearchLogs(ctx, vzaps.WebhookLogSearchRequest{
	InstanceScopedRequest: vzaps.InstanceScopedRequest{
		InstanceID:    "VZ...",
		InstanceToken: "instance-token",
	},
})
fmt.Printf("%#v\n", logs)
```

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

Para filtros avançados como `status`, use `client.Request()` com o body do endpoint de busca na [referência da API](/pt-BR/api-reference/introduction).

## `Webhooks.GetLog(ctx, req)`

Lê um log de entrega específico.

```go theme={null}
log, err := client.Webhooks.GetLog(ctx, vzaps.WebhookLogRequest{
	InstanceScopedRequest: vzaps.InstanceScopedRequest{
		InstanceID:    "VZ...",
		InstanceToken: "instance-token",
	},
	LogID: "log_123",
})
fmt.Printf("%#v\n", log)
```

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

## `Webhooks.RetryLog(ctx, req)`

Repete uma entrega com falha.

```go theme={null}
_, err := client.Webhooks.RetryLog(ctx, vzaps.WebhookLogRequest{
	InstanceScopedRequest: vzaps.InstanceScopedRequest{
		InstanceID:    "VZ...",
		InstanceToken: "instance-token",
	},
	LogID: "log_123",
})
```

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

## Quando usar webhooks

Use webhooks quando:

* sua aplicação já tem URL pública para callbacks;
* quer processar eventos de forma assíncrona no backend;
* seu pipeline de integração já funciona com HTTP POST.

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