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.
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:
{
"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:
{
"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.