Pular para conteúdo

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 - Preencher e-mail para notificações de falha 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.

🔹 Autenticação

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.