# Testar webhooks

Ponha na fila uma entrega webhook.test pelo painel ou pela API, encaminhe eventos do sandbox para a sua máquina com webhooks listen e provoque eventos reais com events trigger.


Há três formas de pôr um receptor à prova antes de receber tráfego real. O envio de teste passa pela fila verdadeira, com assinatura e novas tentativas. O ouvinte da linha de comandos leva os eventos do sandbox até um servidor no seu computador, que um endereço registado não consegue alcançar porque os endereços privados são recusados. O comando de disparo cria registos reais no sandbox para que se produzam eventos genuínos.

## Enviar um evento de teste

No painel, abra **Programadores**, separador **Webhooks**, escolha o endereço e carregue em **Enviar teste**. Aparece a confirmação **Evento de teste enviado** e a entrega surge na lista do endereço. Ao abri-la, vê o **Conteúdo enviado**, cada tentativa com estado e duração, e o **Corpo da resposta** devolvido pelo seu servidor.

A mesma acção pela API exige o âmbito `developer:write`:

```bash
curl -sS -X POST "$BUSINESS_API/developer/webhooks/whk_2kP7vR3nXq9LmT4bW8cYzF1dHsJ/test" \
  -H "Authorization: Bearer $API_KEY"
```

A resposta é `202` com a entrega posta na fila:

```json
{
  "id": "dlv_2kP8aQ5mZr1NcV7xT3bLwE9fGyU",
  "tenant_id": "ten_2jR5wQ8nLm3KxT9vB6cYpZ1dHgF",
  "webhook_id": "whk_2kP7vR3nXq9LmT4bW8cYzF1dHsJ",
  "url": "https://erp.example.test/hooks/billing",
  "event_id": "wev_2kP8aQ4kYt6HdS2wR9nMjC5vBxA",
  "event_type": "webhook.test",
  "status": "pending",
  "attempts": 0,
  "max_attempts": 15,
  "next_attempt_at": "2026-11-19T08:05:12.640391Z",
  "duration_ms": 0,
  "created_at": "2026-11-19T08:05:12.640391Z",
  "sequence": 1
}
```

O campo `data.attributes` do evento contém `{"message": "This is a test event."}`. Consulte `GET $BUSINESS_API/developer/deliveries/{id}` alguns segundos depois para ver a tentativa em `history`. Um endereço desactivado ou pausado responde `409`: retome-o primeiro.

## Encaminhar eventos para a sua máquina

```bash
gotactl webhooks listen --forward-to http://localhost:3000/hook --events invoice.paid,payment.received
```

| Opção | Para que serve |
| :--- | :--- |
| `--forward-to` | Endereço local que recebe os POST encaminhados (obrigatória). |
| `--events` | Lista de tipos de evento a encaminhar, separados por vírgulas. |
| `--poll-interval` | Intervalo entre consultas, só com servidores sem sessões da CLI (por omissão, `1s`). |
| `--live` e `--confirm-live` | Autorizam e confirmam a escuta num contexto real. |

Ao arrancar, o comando abre um endpoint temporário no servidor (`POST /developer/cli-sessions`) e mostra o seu segredo de assinatura `whsec_`, válido só para esta sessão. Depois espera pelos eventos novos (`GET /developer/cli-sessions/{id}/events`, que aguarda até 25 segundos) e envia cada um por `POST` para `--forward-to`, com o corpo completo e os mesmos três cabeçalhos, assinados pelo servidor. Cada encaminhamento imprime uma linha com o tipo, o identificador `wev_`, o código devolvido e o tempo gasto. Ao sair, o comando fecha a sessão; se a CLI deixar de consultar, a sessão expira em cerca de 90 segundos. A única diferença face às entregas reais é que `webhook-id` leva o identificador do evento. Num contexto real, o comando recusa arrancar sem `--live` e `--confirm-live`. A chave precisa de `developer:write` para abrir a sessão e de `developer:read` para a consultar.

## Provocar eventos reais

```bash
gotactl events trigger invoice.paid
```

O comando emite uma factura no sandbox e paga-a através do conector de pagamentos simulado, pelo que `invoice.paid` é produzido de verdade. `gotactl events trigger --list` mostra os tipos suportados: `customer.created`, `account.created`, `invoice.issued`, `invoice.paid`, `payment.received`, `reading.accepted` e `webhook.test`, que envia um teste para o primeiro endereço configurado. Cada evento aparece depois em **Programadores**, separador **Eventos**, com as entregas que gerou.

## Próximos passos

- [Confirmar as assinaturas do que o receptor recebe](/docs/webhooks/verify)
- [O significado de cada estado de entrega](/docs/webhooks/retries)
- [Todos os comandos e opções da linha de comandos](/docs/cli/overview)
- [O que o sandbox contém](/docs/getting-started/sandbox)

