Webhooks — Operação e monitoramento
Seu webhook está no ar e recebendo eventos. Esta página cobre o dia a dia: como tratar duplicatas, manter o endpoint saudável, inspecionar falhas de entrega e reenviar eventos.
Para configurar do zero, veja Webhooks — visão geral. Para a estrutura dos payloads, veja Eventos e payloads.
Trate duplicatas
A entrega é garantida pelo menos uma vez (at-least-once): o mesmo webhook pode chegar de novo em caso de falha de entrega ou reenvio manual.
Cuidado ao escolher a chave de deduplicação: eventos que disparam em criação e atualização (multas, notificações, multas administrativas, veículos) entregam o mesmo id mais de uma vez legitimamente. Duplicata é o mesmo id com o mesmo conteúdo — se o conteúdo mudou, é uma atualização e precisa ser processada. Por isso, não use só event_type + id como chave: inclua o conteúdo do payload.
const crypto = require('crypto');
const eventosProcessados = new Set();
app.post('/webhooks/frota162', async (req, res) => {
// Hash do corpo: reentrega idêntica gera a mesma chave,
// atualização com conteúdo novo gera chave diferente.
const chave = crypto
.createHash('sha256')
.update(JSON.stringify(req.body))
.digest('hex');
if (eventosProcessados.has(chave)) {
return res.status(200).send('Já processado');
}
eventosProcessados.add(chave);
// ... processar evento
res.status(200).send('OK');
});
O exemplo acima usa um Set em memória para simplificar — em produção, persista as chaves processadas (banco ou cache com TTL) para que o controle sobreviva a restarts do seu serviço.
Responda rapidamente
Seu endpoint deve responder com HTTP 200 em menos de 5 segundos. Se o processamento for demorado, salve o payload em fila e processe de forma assíncrona:
app.post('/webhooks/frota162', async (req, res) => {
// Responda imediatamente
res.status(200).send('OK');
// Processe de forma assíncrona
await fila.adicionar(req.body);
});
| Situação | Ação recomendada |
|---|---|
| Notificação processada com sucesso | Retornar HTTP 200 imediatamente |
| Processamento demorado | Retornar HTTP 200 imediatamente, processar em background |
| Notificação duplicada | Retornar HTTP 200 — já foi processada, não retorne erro |
| Erro interno | Retornar HTTP 500 — o evento fica registrado como falha e pode ser reenviado |
Registre logs
Armazene cada notificação recebida (body, timestamp e headers não sensíveis) para auditoria e diagnóstico.
Os headers Authorization e Key carregam o seu access token e a sua assinatura. Remova-os antes de gravar o log — quem tiver acesso ao log conseguiria chamar a API em nome da sua empresa.
Quando uma divergência de contrato ou evento perdido aparecer, o log do seu lado é o que permite comparar com o log de entrega da Frota162.
Liste os erros de entrega
Quando seu servidor retorna erro ou não responde dentro do limite de tempo, a entrega falha e fica registrada no log de erros. O evento não é perdido.
Cada entrada inclui o id do log de erro (necessário para reenvio), a URL de destino, o payload que falhou e o código de resposta recebido (ou o motivo do timeout).
/key/webhooks-errors?pagination[page]=1&pagination[perpage]=50curl -X GET \
'https://apidev.v1.frota162.com.br/key/webhooks-errors?pagination[page]=1&pagination[perpage]=50' \
-H 'Authorization: Basic SEU_ACCESS_TOKEN' \
-H 'Key: SUA_ASSINATURA_HMAC' \
-H 'cache-control: no-cache'
O parâmetro
pagination[perpage]aceita no máximo 100 itens por página. Valores acima de 100 são limitados a 100.
Reenvie um webhook com erro
Reprocessa uma entrega específica usando o id retornado pela listagem de erros.
/key/webhooks/logs/{evento_id}/resendcurl -X POST \
https://apidev.v1.frota162.com.br/key/webhooks/logs/123/resend \
-H 'Authorization: Basic SEU_ACCESS_TOKEN' \
-H 'Key: SUA_ASSINATURA_HMAC' \
-H 'cache-control: no-cache'
Substitua
123peloiddo log de erro obtido na listagem acima.
Solução de problemas
Não estou recebendo notificações
- Confirme se o webhook está cadastrado para o
event_idcorreto — veja o catálogo de eventos - Verifique se o endpoint está acessível publicamente (não é rede interna) e aceita HTTPS
- Se usa allowlist de IP, confirme que os IPs de origem estão liberados
- Verifique os logs do seu lado — há registro de chamadas recebidas?
- Consulte os erros de entrega — se o evento aparece lá, o problema é a resposta do seu endpoint
- Dispare um evento de teste pela plataforma
Meu handler nunca dispara para um tipo de evento
Confira se a comparação do event_type é exata. Os eventos de débito são os únicos em UPPERCASE com prefixo DEBITOS- — se o seu código aplica toLowerCase() antes do match, esses eventos nunca vão bater. Veja o catálogo de eventos.
Estou recebendo duplicatas
Comportamento esperado — a entrega é garantida pelo menos uma vez, e reenvios manuais reprocessam o evento. A solução é idempotência no seu lado, não abertura de chamado.
Monitore seu endpoint
Configure alertas para quando seu endpoint de webhook estiver retornando erros 5xx ou timeouts. Do lado da Frota162 o evento fica registrado como falha, mas quanto antes você detectar do seu lado, menor a fila de reenvio.