Testar webhooks
Ponha na fila uma entrega webhook.test pelo painel ou pela API, encaminhe eventos do sandbox para a sua máquina com webhooks listen e provoque eventos reais com events trigger.
Há três formas de pôr um receptor à prova antes de receber tráfego real. O envio de teste passa pela fila verdadeira, com assinatura e novas tentativas. O ouvinte da linha de comandos leva os eventos do sandbox até um servidor no seu computador, que um endereço registado não consegue alcançar porque os endereços privados são recusados. O comando de disparo cria registos reais no sandbox para que se produzam eventos genuínos.
Enviar um evento de teste#
No painel, abra Programadores, separador Webhooks, escolha o endereço e carregue em Enviar teste. Aparece a confirmação Evento de teste enviado e a entrega surge na lista do endereço. Ao abri-la, vê o Conteúdo enviado, cada tentativa com estado e duração, e o Corpo da resposta devolvido pelo seu servidor.
A mesma acção pela API exige o âmbito developer:write:
curl -sS -X POST "$BUSINESS_API/developer/webhooks/whk_2kP7vR3nXq9LmT4bW8cYzF1dHsJ/test" \
-H "Authorization: Bearer $API_KEY"
A resposta é 202 com a entrega posta na fila:
{
"id": "dlv_2kP8aQ5mZr1NcV7xT3bLwE9fGyU",
"tenant_id": "ten_2jR5wQ8nLm3KxT9vB6cYpZ1dHgF",
"webhook_id": "whk_2kP7vR3nXq9LmT4bW8cYzF1dHsJ",
"url": "https://erp.example.test/hooks/billing",
"event_id": "wev_2kP8aQ4kYt6HdS2wR9nMjC5vBxA",
"event_type": "webhook.test",
"status": "pending",
"attempts": 0,
"max_attempts": 15,
"next_attempt_at": "2026-11-19T08:05:12.640391Z",
"duration_ms": 0,
"created_at": "2026-11-19T08:05:12.640391Z",
"sequence": 1
}
O campo data.attributes do evento contém {"message": "This is a test event."}. Consulte GET $BUSINESS_API/developer/deliveries/{id} alguns segundos depois para ver a tentativa em history. Um endereço desactivado ou pausado responde 409: retome-o primeiro.
Encaminhar eventos para a sua máquina#
gotactl webhooks listen --forward-to http://localhost:3000/hook --events invoice.paid,payment.received
| Opção | Para que serve |
|---|---|
--forward-to |
Endereço local que recebe os POST encaminhados (obrigatória). |
--events |
Lista de tipos de evento a encaminhar, separados por vírgulas. |
--poll-interval |
Intervalo entre consultas, só com servidores sem sessões da CLI (por omissão, 1s). |
--live e --confirm-live |
Autorizam e confirmam a escuta num contexto real. |
Ao arrancar, o comando abre um endpoint temporário no servidor (POST /developer/cli-sessions) e mostra o seu segredo de assinatura whsec_, válido só para esta sessão. Depois espera pelos eventos novos (GET /developer/cli-sessions/{id}/events, que aguarda até 25 segundos) e envia cada um por POST para --forward-to, com o corpo completo e os mesmos três cabeçalhos, assinados pelo servidor. Cada encaminhamento imprime uma linha com o tipo, o identificador wev_, o código devolvido e o tempo gasto. Ao sair, o comando fecha a sessão; se a CLI deixar de consultar, a sessão expira em cerca de 90 segundos. A única diferença face às entregas reais é que webhook-id leva o identificador do evento. Num contexto real, o comando recusa arrancar sem --live e --confirm-live. A chave precisa de developer:write para abrir a sessão e de developer:read para a consultar.
Provocar eventos reais#
gotactl events trigger invoice.paid
O comando emite uma factura no sandbox e paga-a através do conector de pagamentos simulado, pelo que invoice.paid é produzido de verdade. gotactl events trigger --list mostra os tipos suportados: customer.created, account.created, invoice.issued, invoice.paid, payment.received, reading.accepted e webhook.test, que envia um teste para o primeiro endereço configurado. Cada evento aparece depois em Programadores, separador Eventos, com as entregas que gerou.