Webhooks

Webhooks (merchant)

Cadastre URLs HTTPS para receber eventos assinados com HMAC. Doc completa em /docs/webhooks.

Secret whsec_… só aparece completo na criação. Valide X-HyzePay-Signature no raw body.

Criar webhook

Cria endpoint de webhook na conta.

POST/api/merchant-webhooks

Autenticação: sessão do dashboard (cookie Supabase)

Parâmetros

Campo	Tipo	Obrigatório	Descrição
`name`	string	sim	Nome interno
`url`	string	sim	HTTPS público
`events`	string[]	sim	Lista de eventos
`version`	string	não	v1 \| v2 (default v2)
`secret`	string	não	Opcional; gerado se vazio
`isActive`	boolean	não	Default true

Exemplo de body

{
  "name": "Produção",
  "url": "https://api.seusite.com/webhooks/hyzepay",
  "events": ["payment.paid", "checkout.completed", "withdrawal.paid"],
  "version": "v2"
}

Exemplo de resposta

{
  "ok": true,
  "webhook": {
    "id": "uuid",
    "publicId": "wh_…",
    "url": "https://…",
    "events": ["payment.paid"],
    "secret": "whsec_…",
    "version": "v2"
  },
  "secretRevealed": true
}

Listar webhooks

Lista webhooks + catálogo de eventos (eventOptions).

GET/api/merchant-webhooks

Autenticação: sessão do dashboard (cookie Supabase)

Exemplo de resposta

{
  "webhooks": [ /* … */ ],
  "events": [
    { "id": "payment.paid", "label": "…", "description": "…" }
  ]
}

Testar webhook

Envia evento test com assinatura real para validar o endpoint.

POST/api/merchant-webhooks/{id}/test

Autenticação: sessão do dashboard (cookie Supabase)

Exemplo de resposta

{
  "ok": true,
  "result": { "success": true, "statusCode": 200 }
}

Eventos disponíveis

Pagamentos, checkout, assinaturas, transferências, saques e disputas. Catálogo e payloads: Eventos de webhook.

payment.* · checkout.* · subscription.*
transfer.* · withdrawal.* · dispute.*