CLI

Webhooks & Eventos

Escute, encaminhe e depure webhooks em tempo real. A validação HMAC segue o mesmo algoritmo da documentação de Segurança.

Header: X-HyzePay-Signature: t=<unix>,v1=<hex>. Mensagem assinada: ${t}.${rawBody}.

Verificar assinatura

hyzepay webhooks verify \
  --secret whsec_XXXXXXXX \
  --signature 't=1710000000,v1=abcdef...' \
  --body-file payload.json

# ou via stdin / env
export HYZEPAY_WEBHOOK_SECRET=whsec_XXXXXXXX
cat payload.json | hyzepay webhooks verify --signature "$SIG"

Exit code 0 se válida, 1 se inválida ou fora da tolerância (default 300s). Use --tolerance para ajustar.

Assinar (teste)

Gera um header de assinatura para testar o seu endpoint localmente:

hyzepay webhooks sign --secret whsec_XXX --body-file payload.json

# curl de teste
BODY=$(cat payload.json)
SIG=$(hyzepay webhooks sign --secret whsec_XXX --body "$BODY" --json | jq -r .header)
curl -X POST http://localhost:3000/webhooks/hyzepay \
  -H "Content-Type: application/json" \
  -H "X-HyzePay-Signature: $SIG" \
  -H "X-HyzePay-Event: payment.paid" \
  -d "$BODY"

Payload de exemplo

hyzepay webhooks sample payment.paid > payload.json

Emite um envelope v2 no estilo Stripe com type: payment.paid e livemode: false.

Listen & forward

Sobe um receptor HTTP local. Combine com um túnel público (ngrok, cloudflared) e cadastre a URL no dashboard:

# terminal 1 — receptor
hyzepay webhooks listen \
  --port 4242 \
  --secret whsec_XXXXXXXX \
  --forward http://localhost:3000/api/webhooks/hyzepay

# terminal 2 — túnel
ngrok http 4242
# cadastre https://xxxx.ngrok.io no painel HyzePay

Cada POST é logado no terminal (event, signature, body). Com --secret, a CLI valida o HMAC antes de encaminhar. O forward reenvia os headers X-HyzePay-* para o seu app.

Referência

Comando	Descrição
`webhooks verify`	Valida X-HyzePay-Signature
`webhooks sign`	Gera assinatura de teste
`webhooks sample`	Payload payment.paid de demo
`webhooks listen`	Receptor local + opcional forward