# Como funcionam os webhooks

Registe um endereço HTTPS, escolha os tipos de evento e receba cada alteração num POST assinado segundo Standard Webhooks, com envelope JSON v1.


Um webhook é um endereço HTTPS que a empresa regista para receber eventos. Sempre que muda algo que subscreveu, por exemplo uma factura paga ou uma leitura aceite, o servidor guarda um evento e põe na fila uma entrega para cada endereço subscrito. Um processo em segundo plano envia depois o evento por `POST`, assina-o e volta a tentar até o seu servidor responder `2xx` ou a entrega esgotar o prazo.

Os webhooks gerem-se no painel em **Programadores**, separador **Webhooks**, ou pela API. Para ler, a chave de API precisa do âmbito `developer:read`; para criar, alterar ou apagar, de `developer:write`.

## Operações da API

| Operação | Método e caminho |
| :--- | :--- |
| Listar ou criar endereços | `GET`, `POST $BUSINESS_API/developer/webhooks` |
| Ler, alterar ou apagar um | `GET`, `PATCH`, `DELETE $BUSINESS_API/developer/webhooks/{id}` |
| Rodar o segredo de assinatura | `POST $BUSINESS_API/developer/webhooks/{id}/roll` |
| Pôr um evento de exemplo na fila | `POST $BUSINESS_API/developer/webhooks/{id}/test` |
| Acompanhar as entregas | `GET $BUSINESS_API/developer/webhooks/{id}/deliveries` |
| Consultar os tipos de evento | `GET $BUSINESS_API/developer/event-types` |

## Registar um endereço

O campo `url` tem de usar `https` e não pode apontar para endereços privados, de loopback ou link-local; nomes internos como `localhost` também são recusados. O campo `events` recebe nomes de tipos de evento, ou `*` para todos, e `description` aceita até 512 caracteres.

```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": "Sincronização da facturação com o ERP", "events": ["invoice.paid", "payment.received"]}'
```

A resposta `201` traz o campo `secret`, um valor que começa por `whsec_`. Guarde-o logo: as leituras não o mostram, e só a rotação do segredo volta a devolver um, já com o valor novo. Uma leitura posterior do mesmo endereço devolve:

```json
{
  "id": "whk_2kP7vR3nXq9LmT4bW8cYzF1dHsJ",
  "tenant_id": "ten_2jR5wQ8nLm3KxT9vB6cYpZ1dHgF",
  "url": "https://erp.example.test/hooks/billing",
  "description": "Sincronização da facturação com o ERP",
  "events": ["invoice.paid", "payment.received"],
  "enabled": true,
  "created_by": "usr_2mB4tK9qWx1RfZ7nLc3VhP8sDjE",
  "created_at": "2026-11-19T08:02:41.118204Z",
  "updated_at": "2026-11-19T08:02:41.118204Z",
  "health": "healthy",
  "consecutive_failures": 0,
  "api_version": "v1"
}
```

## O que chega ao seu servidor

Cada entrega é um `POST` com `Content-Type: application/json` e três cabeçalhos de assinatura: `webhook-id` (o identificador `dlv_` da entrega), `webhook-timestamp` (segundos Unix) e `webhook-signature`. O corpo é o envelope do evento:

```json
{
  "api_version": "v1",
  "created_at": "2026-11-19T08:05:12.640391Z",
  "data": {
    "attributes": {"message": "This is a test event."},
    "resource": {"id": "whk_2kP7vR3nXq9LmT4bW8cYzF1dHsJ", "sequence": 1, "type": "webhook"},
    "resource_id": "whk_2kP7vR3nXq9LmT4bW8cYzF1dHsJ",
    "resource_type": "webhook"
  },
  "id": "wev_2kP8aQ4kYt6HdS2wR9nMjC5vBxA",
  "request_id": "req_4e8a1c7f3b9d42e6a0c5f8b2d7e1a693",
  "tenant_id": "ten_2jR5wQ8nLm3KxT9vB6cYpZ1dHgF",
  "type": "webhook.test"
}
```

O campo `id` identifica o evento e `type` diz o que aconteceu. `data.resource.sequence` conta os eventos sobre o mesmo registo, o que permite saber qual das alterações é a mais recente. `request_id` só aparece quando a alteração veio de uma chamada à API e corresponde a essa chamada no registo de pedidos.

O seu servidor tem 10 segundos para responder. Os redireccionamentos não são seguidos: um `301` conta como falha.

## Próximos passos

- [Verificar a assinatura de cada entrega](/docs/webhooks/verify)
- [Como as entregas falhadas voltam a ser tentadas](/docs/webhooks/retries)
- [Enviar eventos de teste para o seu receptor](/docs/webhooks/testing)
- [Regras para um receptor fiável em produção](/docs/webhooks/best-practices)

