Visão geral
Webhooks
Pense nos webhooks como “mensagens enviadas pela HyzePay para o seu sistema”, sem que você precise ficar consultando a API o tempo todo.
Por que usar webhooks?
Sem webhooks, sua aplicação teria que perguntar para a API a cada segundo:
“Esse pagamento já foi confirmado?”
Isso é lento e ineficiente.
Com webhooks, a HyzePay avisa você imediatamente:
“O pagamento foi confirmado. Aqui estão os dados.”
Assim você pode:
- atualizar o status de um pedido
- liberar acesso a um produto
- enviar e-mails automáticos
- sincronizar com ERP / CRM
Como funciona na prática?
Quando algo importante acontece na HyzePay (PIX pago, cobrança expirada, disputa aberta…), enviamos um POST HTTPS para a URL que você cadastrou.
Cliente paga PIX
│
▼
Gateway confirma → HyzePay marca pedido como paid
│
▼
POST https://seu-backend.com/webhooks/hyzepay
Headers: X-HyzePay-Signature, X-HyzePay-Event, …
Body: payment.paid (JSON)
│
▼
Seu backend:
1. Valida assinatura HMAC
2. Confere event type = payment.paid
3. Confere status = paid e amount
4. Marca pedido interno (external_id) como pago
5. Responde HTTP 200Não confie só no body sem validar a assinatura. Qualquer um poderia forjar um POST se a URL vazar. Veja Verificação e Segurança.
Criando um webhook no dashboard
- Entre no dashboard HyzePay
- Integração → Webhook
- + Criar webhook
- Preencha os campos abaixo
- Clique em Salvar e copie o secret (só aparece completo na criação)
- Use Enviar teste no menu de ações para validar o endpoint
| Campo | Descrição |
|---|---|
| Versão | Webhook v2 (recomendado) ou v1 |
| Nome | Rótulo interno (ex.: “Produção”) |
| URL | Endpoint HTTPS público do seu servidor |
| Secret | Deixe vazio para gerar (whsec_…) ou defina o seu (16–128 chars) |
| Eventos | Marque ao menos payment.paid |
Limite: 20 webhooks por conta.
Versões (v1 e v2)
v2 (recomendado)
Envelope no estilo Stripe. O objeto do pagamento fica em data.object.
{
"id": "evt_abc123…",
"type": "payment.paid",
"api_version": "v2",
"created": 1710000000,
"created_at": "2026-03-09T12:00:00.000Z",
"livemode": true,
"data": {
"object": {
"id": "uuid-do-pedido",
"status": "paid",
"amount_cents": 1990,
"amount_label": "R$ 19,90",
"currency": "BRL",
"payment_method": "pix",
"external_id": "order_123",
"description": "Plano Pro",
"customer": {
"name": "Maria",
"email": "maria@email.com",
"document": "12345678909",
"phone": null
},
"metadata": { "sku": "PRO-1" },
"correlation_id": "…",
"fee_cents": 59,
"created_at": "…",
"updated_at": "…",
"paid_at": "…",
"expires_at": null
}
},
"source": "hyzepay"
}v1 (legado / flat)
No v1 o objeto do pagamento fica direto em data.
{
"event": "payment.paid",
"event_id": "evt_abc123…",
"created_at": "2026-03-09T12:00:00.000Z",
"livemode": true,
"data": { "id": "…", "status": "paid", "amount_cents": 1990 },
"source": "hyzepay",
"api_version": "v1"
}Headers HTTP
Toda entrega inclui:
| Header | Exemplo | Uso |
|---|---|---|
Content-Type | application/json | Body JSON |
User-Agent | HyzePay-Webhooks/2.0 | Identificação |
X-HyzePay-Event | payment.paid | Tipo do evento |
X-HyzePay-Event-Id | evt_… | ID único do evento |
X-HyzePay-Delivery | dlv_… | ID da tentativa |
X-HyzePay-Webhook-Id | wh_… | ID do webhook |
X-HyzePay-Signature | t=…,v1=hex… | Assinatura HMAC |
X-HyzePay-Api-Version | v2 | Versão do payload |