Introdução
Recebimento de notificações
Quando eventos ocorrem em sua conta (pagamentos recebidos, transferências completadas, etc.), a Moneyguard envia notificações automáticas para a URL configurada no seu webhook.
Toda a comunicação deve ser criptografada via SSL/HTTPS.
A aplicação cliente deve enviar um cabeçalho de Autorização HTTP contendo o token gerado a cada solicitação.
Como funciona
- Evento ocorre- Ex: um QR Code PIX e pago
- Notificação enviada - Moneyguard envia POST para sua URL
- Confirmação - Seu sistema retorna HTTP 2XX
- Retentativa (se necessário) - Em caso de falha, tentamos novamente
Content-Type: application/json
Accept: application/json
User-Agent: Moneyguard-Webhook/1.0
Authorization: {authorization_configurado}
O header Authorization só e enviado se você configurou um valor no campo authorization do webhook.
Respostas esperadas
Seu endpoint deve retornar um código HTTP da família 2XX (200, 201, 202, etc.) para confirmar o recebimento bem-sucedido da notificação.
Exemplos de respostas aceitas
| CÓDIGO | MENSAGEM |
|---|---|
| 200 | Ok |
| 200 | Created |
| 200 | Accepted |
| 200 | No Content |
Timeout: Sua resposta deve ser enviada em até 15 segundos. Após esse tempo, consideramos a entrega como falha.
Processe a notificação de forma assíncrona. Receba o webhook, salve em uma fila/banco de dados, retorne 200 imediatamente, e processe depois. Isso evita timeouts
Estratégia de retentativa
Caso a entrega falhe (timeout, erro de conexão, ou código HTTP diferente de 2XX), a Moneyguard tentara reenviar a notificação automaticamente.
Politica de Retentativa com Backoff Exponencial (Fibonacci)
| TENTATIVA | INTERVALO | TEMPO ACUMULADO |
|---|---|---|
| 1 | Imediato | 0 |
| 2 | 1 minuto | 1 min |
| 3 | 2 minutos | 3 min |
| 4 | 3 minutos | 6 min |
| 5 | 5 minutos | 11 min |
| 6 | 8 minutos | 19 min |
| 7 | 13 minutos | 32 min |
| 8 | 21 minutos | 53 min |
| 9 | 34 minutos | 1h 27 min |
| 10 | 55 minutos | 2h 22 min |
- Total de tentativas: 10
- Tempo máximo de retentativa: Aproximadamente 2 horas e 22 minutos
- Status final: Após 10 tentativas falhas, a notificação e marcada como
error
Tratamento de erros
A Moneyguard registra cada tentativa de entrega com os seguintes dados:
Códigos de Status HTTP
| TIPO DE ERRO | DESCRIÇÃO |
|---|---|
| HTTP 4XX/5XX | Seu servidor retornou erro |
| Connection Refused | Não foi possível conectar ao seu servidor |
| Connection Error | Erro de rede ou host inacessível |
| Timeout Error | esposta não recebida em 15 segundos |
| SSL Error | Problema com certificado SSL/TLS |
| Invalid URL | URL configurada e invalida |
Boas Práticas para Recebimento de Webhook
- Responda rápido: Retorne 200 imediatamente e processe depois
- Idempotencia: Seu sistema deve lidar com notificações duplicadas
- Use
client_ref: Para identificar a transação no seu sistema - Valide o
Authorization: Verifique o header se configurou um token - Logs: Registre todas as notificações recebidas para auditoria
- SSL válido: Use certificado SSL válido (não auto assinado em produção)