PT EN

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#