O que são Webhooks?
Webhooks são mecanismos que permitem a comunicação automática entre sistemas. Sempre que um evento relevante ocorre na Pronttus (como uma transação, transferência, estorno ou infração), enviamos automaticamente uma requisição HTTP POST para uma URL previamente configurada por você.Com webhooks, você não precisa fazer polling (consultas repetidas) para verificar o status das transações. Nós notificamos você automaticamente em tempo real.
Benefícios
Tempo Real
Receba notificações instantâneas assim que os eventos ocorrem
Eficiência
Elimine a necessidade de consultas repetidas (polling)
Confiável
Sistema de retry automático com até 3 tentativas
Seguro
Autenticação via secret e headers customizáveis
Como Funciona
1
Configuração
Você registra uma URL de webhook por tipo de operação (ex: Transferência, Recebimento, Estorno, Infrações) no dashboard da Pronttus
2
Assinatura de eventos
Defina quais eventos específicos deseja receber em cada URL configurada
3
Disparo de evento
Quando um evento ocorre, a Pronttus envia automaticamente uma requisição HTTP POST para a URL associada ao tipo
4
Processamento e resposta
Sua aplicação processa o evento e deve retornar um HTTP 2XX (preferencialmente 200) em até 10 segundos para confirmar o recebimento
Configurando Webhooks
1. Acesse o Dashboard
Entre em app.pronttus.com.br e navegue até a seção Webhooks.2. Configure por Tipo de Operação
A Pronttus permite configurar webhooks específicos para cada categoria de operação:- Transferências - Envios PIX e TEDs
- Recebimentos - Pagamentos e QR Codes PIX
- Estornos - Devoluções e reembolsos
- Infrações - Violações de regras PIX
- Débito/Crédito em conta - Movimentações de saldo
- Outros eventos - Operações futuras
3. Personalize a Configuração
Para cada webhook, você pode configurar:URL de Destino
URL de Destino
Endpoint HTTPS que receberá os eventos. URLs HTTP não são aceitas por questões de segurança.Exemplo:
https://api.sua-empresa.com/webhooks/pronttusE-mail para Notificações
E-mail para Notificações
Receba alertas automáticos quando houver falhas recorrentes na entrega de webhooks
Headers Customizados
Headers Customizados
Adicione headers personalizados para autenticação ou rastreamentoExemplo:
Eventos Específicos
Eventos Específicos
Selecione exatamente quais eventos deseja receber para evitar notificações desnecessárias
Pausar Webhooks
Pausar Webhooks
Pause manualmente o envio de webhooks ou configure pausa automática ao detectar falhas recorrentes
Estrutura da Requisição
Cada webhook é enviado via HTTP POST com os seguintes headers e corpo:Headers Padrão
Sempre
application/jsonUUID único para rastreamento e identificação de reentregas. Use este campo para implementar idempotência
Secret configurado no dashboard para validação de autenticidade. Sempre valide este header!
Payload (Corpo da Requisição)
Campos do Payload
Identificador único do webhook
Tipo do evento (ex:
transactions.receive, transactions.transfer, transactions.chargeback)Objeto contendo os dados específicos do evento. A estrutura varia conforme o tipo de evento
Exemplo de Implementação
Segurança e Validação
Validação do Webhook Secret
Sempre valide o headerx-webhook-secret antes de processar qualquer webhook:
1
Obtenha o Secret
No dashboard da Pronttus, copie o Webhook Secret fornecido ao configurar cada webhook
2
Compare com o Header
Valide se o valor do header
x-webhook-secret corresponde ao secret configurado3
Rejeite se Inválido
Se o secret não corresponder, retorne HTTP 401 e não processe o evento
Retry e Resiliência
Política de Retry
A Pronttus aplica retentativas automáticas quando a entrega de um webhook falha:Quando ocorrem retries?
Quando ocorrem retries?
Erros 4XX ou 5XX acionam nova tentativa automaticamente
Quantas tentativas?
Quantas tentativas?
Serão feitas até 3 novas tentativas em até 10 minutos
Reprocessamento Manual
Reprocessamento Manual
Eventos com falha ficam disponíveis para reprocessamento manual no painel da Pronttus
Notificações
Notificações
Você receberá notificação por e-mail (se configurado) quando houver falhas recorrentes
Códigos de Resposta Esperados
| Código | Descrição | Ação da Pronttus |
|---|---|---|
| 2XX | Evento recebido com sucesso | Webhook marcado como entregue |
| 4XX | Falha no envio (problema no seu endpoint) | Retry automático |
| 5XX | Falha no envio (servidor indisponível) | Retry automático |
Idempotência
Webhooks podem ser entregues mais de uma vez. Implemente idempotência usando o headerx-correlation-id:
Boas Práticas
Responda em até 10 segundos
Responda em até 10 segundos
Seu endpoint deve retornar status 200 em até 10 segundos. Processe operações demoradas de forma assíncrona.
Use HTTPS obrigatoriamente
Use HTTPS obrigatoriamente
Rejeite requisições não HTTPS. A Pronttus só envia webhooks para URLs HTTPS.
- Configure certificado SSL válido
- Nunca aceite webhooks em URLs HTTP
- Use TLS 1.2 ou superior
Autenticação via Header
Autenticação via Header
Utilize autenticação via header customizado para segurança adicional:
Rastreamento com correlation-id
Rastreamento com correlation-id
Use o
x-correlation-id para rastrear reentregas e debugar problemas:Armazene os Webhooks
Armazene os Webhooks
Salve todos os webhooks recebidos em um banco de dados para auditoria e reprocessamento.
Trate Erros Corretamente
Trate Erros Corretamente
Implemente try-catch robusto. Retorne 200 para erros de lógica de negócio, mas 5XX para erros de infraestrutura.
Monitore e Alerte
Monitore e Alerte
Configure alertas para webhooks que falham repetidamente:
- Monitore taxa de sucesso/falha
- Alerte quando houver múltiplas falhas
- Verifique tempo de resposta
- Use APM (New Relic, Datadog, etc)
Implemente Idempotência
Implemente Idempotência
Sempre implemente idempotência usando o
x-correlation-id para evitar processar o mesmo evento múltiplas vezes:- Use banco de dados ou cache (Redis)
- Armazene o correlation-id dos eventos processados
- Verifique antes de processar
- Retorne 200 para eventos duplicados
Testando Webhooks Localmente
Use ferramentas como ngrok para expor seu localhost durante o desenvolvimento:Testando Manualmente
Você pode testar seu endpoint manualmente com cURL:Ambiente Sandbox
O suporte a Webhooks no ambiente de sandbox está em desenvolvimento. Alguns eventos podem não estar disponíveis para testes ainda.Consulte nossa equipe de suporte para informações atualizadas sobre a disponibilidade de webhooks em sandbox.
Suporte e Ajuda
Precisa de ajuda com webhooks? Nossa equipe está disponível:| Canal | Informação |
|---|---|
| E-mail Técnico | [email protected] |
| +55 (11) 99999-9999 | |
| Horário | Segunda a Sexta, 9h às 18h (BRT) |
| Dashboard | app.pronttus.com.br |