Webhook
Referência da API
Em Homologação:
Swagger - API de Serviços Pedágio Eletrônico Senatran v3
Em Produção:
API de Serviços Pedágio Eletrônico Senatran v3
Configuração
🔹 Preencher URL do Webhook no Portal do Pedágio Eletrônico Senatran
🔹 Opcional - Prencher Chave da API do Webhook no Portal do Pedágio Eletrônico Senatran
🔹 Opcional - Nosso sistema envia requisições de webhook a partir dos seguintes IPs de origem 189.9.78.0/28, 189.9.79.228:80 e 189.9.115.12, caso desejem configurar a liberação destes no firewall para permitir o recebimento das notificações.
Tempo de Retorno
Em homologação a cada 2 mim.
Em produção a cada 1 minuto, ou até completar o lote (100 registros), o que acontecer antes.
Em caso de erro vai aumentando o tempo entre as tentativas exponencialmente até 2h.
Notificações de Falha do Webhook
Após pelo menos 10 falhas de comunicação com o webhook da concessionária, será enviado um e-mail diário para o endereço configurado no campo E-mail para Notificações de Falha do Webhook.
O remetente da notificação será monitoracao-pedagio-eletronico@serpro.gov.br.
A contagem é reiniciada sempre que houver uma comunicação com sucesso.
Retornos
Registro persistido na base: quando webhook retorna "sucesso": true, sem informação no campo motivo, significa que evento de inclusão/alteração foi persistido na base.
Registro não persistido na base: quando webhook retorna "sucesso": false, significa que evento de inclusão/alteração não foi persistido na base conforme campo motivo;
Registro persistido na base com ressalvas: quando Webhook retorna "sucesso": true, e mensagem no campo motivo, significa que foi persistido e a informação do campo motivo é um alerta para a concessinária de alguma situação (Ex: Placa {placa} não encontrada no sistema Renavam para a passagem {UUID}.)
Registro cancelado na base: quando Webhook retorna "sucesso": true, "tipo": 1, "status": 2, significa que o registro de passagem e por consequência o de pagamento foram cancelados.
Observações
Não existe impedimento de enviar o registro de pagamento antes do retorno do registro de passagem. O que pode acontecer é, no caso de erro no registro de passagem, o registro de pagamento retornar erro de passagem não encontrada para pagamento.
A recomendação é a adoção do Processamento Assíncrono: o endpoint do webhook deve confirmar o recebimento do lote recebido imediatamente (HTTP 200 OK ou HTTP 202 Accepted), realizando o processamento em segundo plano (background). Seguir este modelo otimiza a performance e evita a retenção da conexão síncrona, que eleva o risco de timeouts e reenvios desnecessários, comprometendo a estabilidade e a escalabilidade da integração.