> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rivoopay.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Webhooks
> Configure webhooks para receber notificações automáticas sobre eventos de pagamento em tempo real
## O que são Webhooks?
Webhooks são requisições HTTP POST enviadas automaticamente para uma URL de sua escolha sempre que eventos específicos ocorrem em nossa plataforma. Isso permite que sua aplicação seja notificada instantaneamente sobre mudanças no status de pagamentos, sem a necessidade de fazer polling constante na API.
## Como Configurar Webhooks
### Acessando a Configuração
Para configurar seus webhooks, siga este caminho na plataforma:
1. **Menu Lateral** → **Desenvolvedor** → **Webhooks**
2. Clique em **"Criar Webhook"**
3. Configure a URL de destino e eventos desejados
**Importante**: Certifique-se de que sua URL de webhook esteja acessível publicamente e possa receber requisições POST.
### Configurações Necessárias
* **URL do Endpoint**: URL onde você receberá as notificações
* **Eventos**: Selecione quais eventos deseja receber
* **Descrição**: Nome identificador para o webhook
* **Status**: Ativo/Inativo
## Eventos Disponíveis
Nossa plataforma oferece 5 tipos de eventos de webhook, todos retornando informações completas da charge:
### 1. Charge.Pending (Charge Criada)
Disparado quando uma nova cobrança é criada no sistema.
```json theme={null}
{
"event": "Charge.Pending",
"charge": {
"id": "chg_abc123",
"status": "pending",
"amount": 10000,
"currency": "BRL",
"created_at": "2025-12-15T10:30:00Z",
// ... outras informações da charge
}
}
```
**Quando ocorre:**
* Link de pagamento é criado
* Cobrança é gerada via API
* Cliente acessa o link mas ainda não iniciou o pagamento
### 2. Charge.Processing
Disparado quando o pagamento está sendo processado.
```json theme={null}
{
"event": "Charge.Processing",
"charge": {
"id": "chg_abc123",
"status": "processing",
"total": 10000,
// ... outras informações da charge
}
}
```
**Quando ocorre:**
* Cliente confirma o pagamento
* Transação é enviada para processamento
* Aguardando confirmação da operadora
### 3. Charge.Paid
Disparado quando o pagamento é confirmado como pago.
```json theme={null}
{
"event": "Charge.Paid",
"charge": {
"id": "chg_abc123",
"status": "paid",
"total": 10000,
// ... outras informações da charge
}
}
```
**Quando ocorre:**
* Pagamento é aprovado pela operadora
* Transação PIX é confirmada
* Boleto é compensado
### 4. Charge.Received (Valor Disponível para Saque)
Disparado quando o valor da cobrança fica disponível para saque.
```json theme={null}
{
"event": "Charge.Received",
"charge": {
"id": "chg_abc123",
"status": "received",
"total": 10000,
// ... outras informações da charge
}
}
```
**Quando ocorre:**
* Período de análise de risco finalizado
* Valor liberado para saque
* Disponível no saldo da conta
### 5. Charge.Expired
Disparado quando uma cobrança expira sem ser paga.
```json theme={null}
{
"event": "Charge.Expired",
"charge": {
"id": "chg_abc123",
"status": "expired",
"total": 10000,
// ... outras informações da charge
}
}
```
**Quando ocorre:**
* Data de vencimento é ultrapassada
* Link de pagamento expira
* Cobrança é cancelada automaticamente
## Implementação do Endpoint
### Estrutura Básica
Seu endpoint deve:
1. **Aceitar POST** requests
2. **Responder com status 200** para confirmar recebimento
3. **Processar rapidamente** (timeout de 30 segundos)
4. **Validar a assinatura** para segurança
### Exemplo de Implementação
```javascript theme={null}
app.post('/webhook', express.raw({type: 'application/json'}), (req, res) => {
const payload = req.body
const event = JSON.parse(payload);
switch(event.event) {
case 'Charge.Pending':
// Lógica para charge criada
break;
case 'Charge.Processing':
// Lógica para charge em processamento
break;
case 'Charge.Paid':
// Lógica para charge paga
break;
case 'Charge.Received':
// Lógica para valor disponível
break;
case 'Charge.Expired':
// Lógica para charge expirada
break;
}
res.status(200).send('OK');
});
```
## Tentativas de Entrega
### Política de Retry
* **Tentativas**: Até 5 tentativas
* **Intervalos**: 1min, 5min, 15min, 1h, 6h
* **Timeout**: 30 segundos por tentativa
* **Status de sucesso**: 200-299
### Logs de Webhook
Na plataforma você pode acompanhar:
* ✅ **Entregas bem-sucedidas**
* ❌ **Falhas de entrega**
* 🔄 **Tentativas de retry**
* 📊 **Histórico completo**
## Testando Webhooks
### No Modo Teste
Durante o desenvolvimento, use o modo teste para:
1. **Simular pagamentos** e receber webhooks
2. **Validar sua implementação** sem transações reais
3. **Testar todos os eventos** de forma controlada
4. **Debug** com logs detalhados
### Ferramentas Recomendadas
* **ngrok**: Para expor localhost publicamente
* **Postman**: Para testar endpoints
* **curl**: Para testes rápidos via terminal
**Dica**: Use ferramentas como ngrok durante o desenvolvimento para testar webhooks localmente antes de fazer deploy.
## Perguntas Frequentes
Sim, você pode configurar múltiplos webhooks com URLs diferentes e eventos específicos para cada um.
O sistema tentará reenviar o webhook seguindo nossa política de retry. Após 5 tentativas sem sucesso, o webhook será marcado como falhou.
Use ferramentas como ngrok para expor seu ambiente local ou configure um servidor de testes acessível publicamente.
Sim, na configuração do webhook você pode selecionar especificamente quais eventos deseja receber.
## Suporte
Se você encontrar problemas com webhooks ou precisar de ajuda na implementação:
* **Email**: [contato@clickpay.app.br](mailto:contato@clickpay.app.br)
* **Chat**: Disponível no painel de controle
* **Documentação**: Consulte outros guias técnicos
**Importante**: Sempre teste seus webhooks extensivamente no ambiente de teste antes de ativar em produção.