PT EN

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.

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.

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.

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="
}

5. Enviar uma entrega de teste#

bash
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.

Próximos passos#