# Ouvir eventos com webhooks

Receba eventos assinados no seu servidor, valide os cabeçalhos Standard Webhooks, teste em local com a CLI e registe o endpoint definitivo pela API.


## O que vai construir

Um receptor HTTP que só aceita entregas com assinatura válida, ligado primeiro à sua máquina através da CLI e depois registado como endpoint permanente da empresa. No fim terá um `whk_` activo, subscrito a `payment.received` e `invoice.paid`, e terá visto uma entrega de teste chegar com resposta `200`.

Cada entrega é um `POST` com corpo JSON e três cabeçalhos: `webhook-id`, `webhook-timestamp` (segundos Unix) e `webhook-signature`, no formato `v1,<base64>`. A assinatura é um HMAC-SHA256 de `id.timestamp.corpo` calculado com o segredo `whsec_` do endpoint. Durante a rotação de um segredo chegam dois valores `v1,` separados por espaço, um por segredo.

## Pré-requisitos

- Uma sandbox activa e a CLI `gotactl` com sessão iniciada nessa sandbox (`gotactl auth login`).
- Uma chave de API de teste com `developer:write` (criar o endpoint e enviar o teste) e `developer:read` (ler as entregas).
- Node.js 20 ou mais recente para correr o receptor de exemplo em `examples/webhook-receiver` (há também versões em Python e Go na mesma pasta).

## 1. Encaminhar eventos da sandbox para a sua máquina

O endereço registado num endpoint tem de ser `https` público; `localhost` é recusado. Para desenvolver, a CLI lê os eventos da sandbox e reenvia-os, assinados, para um URL local.

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

A opção `--events` limita o reencaminhamento aos tipos indicados, separados por vírgulas, e `--poll-interval` muda o intervalo de consulta, usado só com servidores sem sessões da CLI (por omissão `1s`). Num contexto de produção o comando só corre com `--live` e `--confirm-live`.

✓ Checkpoint: a CLI escreve no terminal o segredo de assinatura desta sessão, começado por `whsec_`. Copie-o; muda sempre que o comando volta a arrancar.

## 2. Arrancar o receptor com esse segredo

Noutro terminal, a partir da pasta `examples/webhook-receiver`:

```bash
WEBHOOK_SECRET="whsec_/zemf1hlS/YnhOJXSiMlQtDMjsSCnb3T2EH3ZndfbrU=" node node/server.mjs
```

O receptor recusa com `400` qualquer pedido sem os três cabeçalhos, com um `webhook-timestamp` afastado mais de 300 segundos da hora actual ou com uma assinatura que não confere.

✓ Checkpoint: o processo escreve `listening on http://127.0.0.1:3000/hook`.

## 3. Disparar um evento real

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

Este comando emite e paga uma factura na sandbox através do conector de pagamento simulado, por isso gera tanto `payment.received` como `invoice.paid`.

✓ Checkpoint: o terminal de `webhooks listen` mostra uma linha por evento reencaminhado, como `2026-11-19T09:10:02Z  --> invoice.paid [wev_3x6bknQybCmscpyDKTJXSdTOBT7]  <-- 200 OK (8ms)`, e o receptor imprime `verified event invoice.paid` seguido do `id` do evento.

## 4. Registar o endpoint definitivo

Quando o receptor estiver publicado num endereço `https` acessível pela internet, registe-o. O URL não pode ter credenciais nem fragmento, tem no máximo 2048 caracteres e deve resolver para um endereço público.

```bash
curl -sS -X POST "$BUSINESS_API/developer/webhooks" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://erp.example.test/hooks/billing","description":"ERP: cobranças e facturas pagas","events":["payment.received","invoice.paid"]}'
```

Resposta `201 Created`, resumida:

```json
{
  "id": "whk_3d68SShcDvNgBfM7XueBaFfs63I",
  "url": "https://erp.example.test/hooks/billing",
  "description": "ERP: cobranças e facturas pagas",
  "events": ["payment.received", "invoice.paid"],
  "enabled": true,
  "created_by": "key_3f5kSeI9SXDLwgbb5hilkGVvprT",
  "created_at": "2026-11-19T09:12:44Z",
  "updated_at": "2026-11-19T09:12:44Z",
  "secret": "whsec_YUxdKD/3IFzwZ1TJmMdEtQDKO9Lmv4squeePTNoymRo="
}
```

✓ Checkpoint: o campo `secret` vem preenchido. Guarde-o já no seu cofre de segredos: as leituras seguintes do endpoint nunca o devolvem. Use `["*"]` em `events` para receber todos os tipos do catálogo.

## 5. Enviar uma entrega de teste

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

✓ Checkpoint: a resposta `202` traz uma entrega com `"event_type": "webhook.test"`, `"status": "pending"` e um `id` começado por `dlv_`. Um endpoint pausado ou desactivado responde `409`.

## Testar

Siga a entrega com `GET $BUSINESS_API/developer/webhooks/whk_3d68SShcDvNgBfM7XueBaFfs63I/deliveries`: o `status` passa a `succeeded` quando o seu servidor responde com um código 2xx. No painel, abra **Programadores** e o separador **Webhooks**, escolha o endpoint e use **Enviar teste**; a lista **Entregas** mostra cada tentativa com o estado e o código HTTP devolvido.

Se o servidor falhar, a entrega volta a ser tentada após 30 s, 2 min, 10 min, 30 min, 1 h, 2 h, 4 h e 8 h, e depois de 12 em 12 horas, até 15 tentativas ou 72 horas. Um `410` pausa o próprio endpoint e as entregas ficam em `paused` até alguém usar **Retomar**. Qualquer outro erro 4xx é repetido duas vezes e a entrega fica retida em `paused`; depois de corrigir o receptor, **Reenviar falhadas**, no menu do endpoint, devolve à fila as entregas retidas e falhadas.

## Próximos passos

- [Verificar assinaturas em Node.js, Python e Go](/docs/webhooks/verify)
- [Calendário de novas tentativas e reenvios em massa](/docs/webhooks/retries)
- [Boas práticas: responder depressa e ignorar duplicados pelo webhook-id](/docs/webhooks/best-practices)
- [Receber pagamentos e confirmar a liquidação por webhook](/docs/guides/receive-payments)

