PT EN

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:

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

json
{
  "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#

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

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

Próximos passos#