Webhooks - Visão Geral
Webhooks permitem que você receba notificações em tempo real sobre mudanças de status de suas transações.
Como Funciona
- Configure uma URL de webhook no seu dashboard ou via API
- Quando um evento ocorrer, enviamos uma requisição POST para sua URL
- Valide a assinatura HMAC para garantir autenticidade
- Processe o evento conforme necessário
Eventos Disponíveis
| Evento | Descrição |
|---|---|
charge.created |
Cobrança criada |
charge.paid |
Cobrança paga |
charge.failed |
Cobrança falhou |
charge.refunded |
Cobrança reembolsada |
charge.cancelled |
Cobrança cancelada |
payout.created |
Saque criado |
payout.completed |
Saque concluído |
payout.failed |
Saque falhou |
Configurar Webhook
Você pode configurar webhooks de duas formas:
1. Webhook Global (Dashboard)
Configure webhooks globais no dashboard que serão enviados para todas as cobranças:
POST /v1/webhooks
{
"url": "https://seusite.com.br/webhook",
"events": ["charge.paid", "charge.failed"]
}2. Callback URL Pontual (por Cobrança)
Você também pode enviar um callback_url no payload de criação da cobrança para receber notificações apenas desta cobrança específica:
POST /v1/charges
{
"amount": 10000,
"payment_method": "pix",
"callback_url": "https://seusite.com.br/callback/order-123",
"customer": { ... }
}Vantagens do callback_url:
- Permite URLs diferentes por cobrança
- Útil para integrações pontuais sem configurar webhook global
- Funciona em conjunto com webhooks globais
- Ideal para casos onde cada pedido precisa de um endpoint específico
Nota: O callback_url recebe as mesmas notificações que os webhooks globais, mas apenas para a cobrança específica onde foi informado. Ambos os sistemas funcionam simultaneamente.