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
gotactlcom sessão iniciada nessa sandbox (gotactl auth login). - Uma chave de API de teste com
developer:write(criar o endpoint e enviar o teste) edeveloper: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.
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.
2. Arrancar o receptor com esse segredo#
Noutro terminal, a partir da pasta examples/webhook-receiver:
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.
3. Disparar um evento real#
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.
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.
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:
{
"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="
}
5. Enviar uma entrega de teste#
curl -sS -X POST "$BUSINESS_API/developer/webhooks/whk_3d68SShcDvNgBfM7XueBaFfs63I/test" \
-H "Authorization: Bearer $API_KEY"
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.