Webhooks — Eventos e payloads
Referência do corpo de cada evento de webhook. Para configurar o recebimento, veja Webhooks — visão geral. Para tratamento de duplicatas e falhas, veja Operação e monitoramento.
Catálogo de eventos
O event_id é usado no cadastro do webhook; o event_type é o discriminador que chega no payload. Use esta tabela para ligar os dois. As seções desta página seguem a mesma ordem dos event_id.
event_id | Evento | event_type no payload | Payload |
|---|---|---|---|
1 | Nova multa cadastrada | frame | Multas |
2 | Atualização de multa | frame | Multas |
3 | Nova notificação cadastrada | notification | Notificações |
4 | Atualização de notificação | notification | Notificações |
5 | Taxa de IPVA | DEBITOS-IPVA | Débitos |
6 | Taxa de DPVAT | DEBITOS-DPVAT | Débitos |
7 | Taxa de licenciamento | DEBITOS-LICENCIAMENTO | Débitos |
8 | Cronotacógrafo | cronotacografo | Cronotacógrafo |
9 | Dados de veículo novos | car | Veículo |
10 | Atualização de dados de veículo | car | Veículo |
11 | Status de indicação de condutor (API v2) | driver_indication | Indicação de condutor |
12 | Multa administrativa | administrative_frame.created · administrative_frame.updated | Multas administrativas |
Multas administrativas usam um único cadastro (event_id 12) para criação e atualização; o momento chega no event_type do payload.
DEBITOS-Os event_type de débito (DEBITOS-IPVA, DEBITOS-DPVAT, DEBITOS-LICENCIAMENTO) são os únicos em UPPERCASE com o prefixo DEBITOS-. Todos os demais eventos usam event_type em lowercase.
A comparação no seu handler deve ser exata — não aplique toLowerCase() nem qualquer normalização de case antes do match. Se normalizar, DEBITOS-IPVA vira debitos-ipva e nunca vai bater.
Objetos compartilhados
Blocos que aparecem em mais de um evento, com a mesma semântica.
Nas tabelas desta página, a coluna Nulo indica se o campo pode chegar com valor null. Salvo indicação em contrário na seção do evento, os campos listados estão sempre presentes no payload — um campo sem valor chega como null, não é omitido.
Objeto car
| Campo | Tipo | Nulo | Descrição |
|---|---|---|---|
car_id | number | sim | ID do veículo na Frota162. Sempre null em multas administrativas, que não são vinculadas a um veículo cadastrado |
car_plate | string | não | Placa do veículo |
O evento de Cronotacógrafo usa um bloco car diferente (chaves id/plate e campos extras) — veja a seção do evento.
Objeto driver
Dados do condutor indicado. Os campos têm valor quando driver_indicate for 1; quando 0, chegam sem valor.
| Campo | Tipo | Nulo | Descrição |
|---|---|---|---|
id | number | sim | ID do condutor na Frota162 |
indicate | string | sim | Data/hora da indicação — ISO-8601 UTC |
name | string | sim | Nome do condutor |
license | string | sim | Número da CNH |
identification | string | sim | RG |
identification_state | string | sim | UF de emissão do RG |
tax_id | string | sim | CPF |
address | string | sim | Logradouro |
address_number | string | sim | Número do endereço |
distric | string | sim | Bairro |
city | string | sim | Município |
state | string | sim | UF |
Campos presentes apenas em Multas e Notificações (não existem em multas administrativas): indicated_recieve_doc_at, indicated_sent_doc_org_at, address_zip_code. Em multas administrativas o CEP chega como addres_zip_code — grafias distintas entre eventos, compare o valor exato.
Objeto organization
| Campo | Tipo | Nulo | Descrição |
|---|---|---|---|
organization_code | number | string | sim | Código do órgão autuador. Chega como number em multas/notificações e como string em multas administrativas |
organization_name | string | sim | Nome do órgão autuador |
Objeto payment
| Campo | Tipo | Nulo | Descrição |
|---|---|---|---|
paid | boolean | não | Indica se a multa consta como paga |
at | string | sim | Data do pagamento no formato YYYY-MM-DD. null quando não há data registrada |
amount | number | não | Valor pago. 0 quando não há valor registrado |
paid pode ser true com at: null e amount: 0Nem sempre a data e o valor do pagamento estão disponíveis: paid pode vir true com at em null e amount em 0. Use paid como fonte de verdade para saber se a multa foi paga; não infira o pagamento a partir de at/amount.
Multas — frame
event_id: 1 (criação), 2 (atualização) · dispara quando uma infração é registrada ou atualizada.
Mapa do payload: raiz (event_type, id, company_id, link, linkFrame, sne_boleto_status, created_at, updated_at) + blocos car · frame · organization · driver · payment
{
"event_type": "frame",
"id": 1,
"company_id": 1,
"car": {
"car_id": 1,
"car_plate": "ABC1234"
},
"frame": {
"ait": "R1111111",
"type": "MULTA",
"at": "2024-01-11",
"time": "20:26:00",
"expiration_at": "2024-03-02",
"code": "74550",
"description": "TRANSITAR EM VELOCIDADE SUPERIOR A MAXIMA PERMITIDA EM ATE 20%",
"address": "RUA AFONSO GARBUIO, N. 790",
"city_code": "3550308",
"city": "SAO PAULO",
"state": "SP",
"points": 4,
"amount": 130.16,
"discount_amount": 104.13,
"driver_indicate": 1,
"treated": true
},
"organization": {
"organization_code": 1,
"organization_name": "DETRAN-SP"
},
"driver": {
"id": 456,
"indicate": "2024-01-20T10:00:00.000Z",
"indicated_recieve_doc_at": "2024-01-21T10:00:00.000Z",
"indicated_sent_doc_org_at": "2024-01-22T10:00:00.000Z",
"name": "JOAO DA SILVA",
"license": "12345678900",
"identification": "123456789",
"identification_state": "SP",
"tax_id": "12345678909",
"address": "RUA EXEMPLO",
"address_number": "100",
"address_zip_code": "01000-000",
"distric": "SP",
"city": "SAO PAULO",
"state": "SP"
},
"payment": {
"paid": true,
"at": "2024-02-01",
"amount": 104.13
},
"link": "https://boleto.example.com/abc123",
"linkFrame": "https://documento.example.com/abc123.pdf",
"sne_boleto_status": "PAGO",
"created_at": "2024-04-05T20:49:18.000Z",
"updated_at": "2024-04-06T09:00:00.000Z"
}
Campos próprios do evento
| Campo | Tipo | Nulo | Descrição |
|---|---|---|---|
frame.ait | string | não | Número do Auto de Infração de Trânsito |
frame.type | string | sim | Tipo da infração |
frame.at / frame.time | string | sim | Data (YYYY-MM-DD) e hora (HH:MM:SS) da infração |
frame.expiration_at | string | sim | Data de vencimento (YYYY-MM-DD) |
frame.code | string | sim | Código da infração no CTB |
frame.city_code | string | sim | Código IBGE da cidade |
frame.points | number | sim | Pontos na CNH |
frame.amount / frame.discount_amount | number | sim | Valor original e valor com desconto, em reais |
frame.driver_indicate | number | não | 0 = condutor não indicado, 1 = indicado. Quando 1, o objeto driver vem com valores |
frame.treated | boolean | não | true se o cliente marcou a multa como tratada na plataforma, false caso contrário |
link | string | sim | Link do boleto |
linkFrame | string | sim | Link do documento oficial da infração (também conhecido como "espelho da multa", é o mesmo documento da notificação de mesmo AIT). null quando o documento não estiver disponível |
sne_boleto_status | string | sim | Status do boleto no SNE (Sistema de Notificação Eletrônica) |
frame.treated: tratativa marcada pelo cliente- O valor vem da marcação que o cliente faz na plataforma. É sempre booleano, nunca
null: sem marcação, chegafalse. - Registro novo (
event_id 1) sempre chega comfalse, porque toda multa nasce não tratada. - Uma nova captura dos dados da multa não desfaz a marcação do cliente.
- Quando a tratativa muda, o valor novo chega no webhook de atualização (
event_id 2), como os demais campos. - O status do recurso e a justificativa da tratativa não fazem parte do payload.
link vs. linkFramelinkcontém o link do boleto para pagamento;linkFramecontém o link do documento oficial da infração (espelho da multa) — seguindo o mesmo padrão do campolinkNotificationno eventonotification.nullemlinkFrameindica que o documento ainda não está disponível, não um erro. O campo pode vir preenchido em uma atualização posterior da multa (event_id 2).
Objetos compartilhados: car · driver · organization · payment
Notificações — notification
event_id: 3 (criação), 4 (atualização) · dispara quando uma notificação de infração é registrada ou atualizada.
Mapa do payload: raiz (event_type, id, company_id, link, linkNotification, sne_boleto_status, created_at, updated_at) + blocos car · notification · organization · driver
{
"event_type": "notification",
"id": 1,
"company_id": 1,
"car": {
"car_id": 1,
"car_plate": "ABC1234"
},
"notification": {
"ait": "N1234567",
"at": "2024-01-11",
"time": "20:26:00",
"indication_limit_at": "2024-02-11",
"code": "74550",
"description": "TRANSITAR EM VELOCIDADE SUPERIOR A MAXIMA PERMITIDA",
"address": "RUA EXEMPLO, 100",
"city_code": "3550308",
"city": "SAO PAULO",
"state": "SP",
"amount": 130.16,
"discount_amount": 104.13,
"driver_indicate": 1,
"points": 4,
"treated": false
},
"organization": {
"organization_code": 1,
"organization_name": "DETRAN-SP"
},
"driver": {
"id": 456,
"indicate": "2024-01-20T10:00:00.000Z",
"indicated_recieve_doc_at": "2024-01-21T10:00:00.000Z",
"indicated_sent_doc_org_at": "2024-01-22T10:00:00.000Z",
"name": "JOAO DA SILVA",
"license": "12345678900",
"identification": "123456789",
"identification_state": "SP",
"tax_id": "12345678909",
"address": "RUA EXEMPLO",
"address_number": "100",
"address_zip_code": "01000-000",
"distric": "SP",
"city": "SAO PAULO",
"state": "SP"
},
"link": "https://boleto.example.com/abc123",
"linkNotification": "https://notificacao.example.com/abc123",
"sne_boleto_status": "PENDENTE",
"created_at": "2024-04-05T20:49:18.000Z",
"updated_at": "2024-04-06T09:00:00.000Z"
}
Campos próprios do evento
O bloco notification tem os mesmos campos do bloco frame de Multas, com um adicional:
| Campo | Tipo | Nulo | Descrição |
|---|---|---|---|
notification.indication_limit_at | string | sim | Prazo-limite para indicar o condutor (YYYY-MM-DD) |
notification.treated | boolean | não | true se o cliente marcou a notificação como tratada na plataforma, false caso contrário. Segue as mesmas regras de frame.treated: notificação nova chega com false e a mudança de tratativa chega no webhook de atualização (event_id 4) |
linkNotification | string | sim | Link da notificação, além do link do boleto |
Objetos compartilhados: car · driver · organization
Débitos — DEBITOS-*
event_id: 5 (IPVA), 6 (DPVAT), 7 (licenciamento) · dispara apenas na criação do registro do débito.
O mesmo formato se aplica aos três — o event_type muda conforme o tributo: DEBITOS-IPVA, DEBITOS-DPVAT, DEBITOS-LICENCIAMENTO.
{
"event_type": "DEBITOS-IPVA",
"id": 1,
"company_id": 1,
"car": {
"car_id": 1,
"car_plate": "ABC1234"
},
"ammount": 1250.00,
"exercise": "2024",
"occurrence": "01",
"expedition_at": "2024-01-31",
"quote": 1,
"created_at": "2024-01-15T10:00:00.000Z",
"updated_at": null
}
Campos próprios do evento
| Campo | Tipo | Nulo | Descrição |
|---|---|---|---|
ammount | number | não | Valor do tributo em reais — grafia com dois m, mantida por compatibilidade |
exercise | string | não | Ano-exercício do tributo |
occurrence | string | não | Ocorrência |
expedition_at | string | sim | Data de expedição (YYYY-MM-DD) |
quote | number | não | Cota/parcela |
updated_at | null | sempre | Sempre null — o evento só dispara na criação |
Objetos compartilhados: car
updated_at sempre chega nullEventos de débito são disparados apenas na criação do registro — atualizações posteriores do débito não geram webhook. Todo payload recebido representa um novo débito; trate como inserção, sem diferenciar criação de atualização.
Escopo: apenas IPVA, DPVAT e Licenciamento geram webhook. Outros tipos de débito (DETRAN, DER, DERSA, CETESB, RENAINF, municipais, polícia rodoviária) são registrados no sistema, mas não geram webhook.
Cronotacógrafo — cronotacografo
event_id: 8 · dispara quando um novo certificado de cronotacógrafo é registrado para um veículo da frota.
O cronotacógrafo é o equipamento que registra velocidade e tempo de direção, obrigatório em veículos de carga e transporte de passageiros. O certificado é emitido após a verificação do INMETRO, que envolve a lacração do equipamento (bloco sealing) e o ensaio de aferição em posto autorizado (bloco rehearsal).
Mapa do payload: raiz (event_type, id, company_id, link, created_at, updated_at) + blocos car · gru · result · sealing · rehearsal
{
"event_type": "cronotacografo",
"id": 1,
"company_id": 1,
"car": {
"id": 1,
"rim": "22.5",
"tire": "295/80",
"renavam": "00123456789",
"plate": "ABC1234",
"chassi": "9BWZZZ377VT004251"
},
"gru": {
"number": "00190000090123456789",
"ammount": "150.00",
"payment_at": "2024-01-10T14:00:00.000Z"
},
"result": {
"issue_at": "2024-01-01T00:00:00.000Z",
"expiration_at": "2025-01-01T00:00:00.000Z",
"document": "CERTIFICADO",
"document_number": "123456",
"responsible": "FULANO DE TAL"
},
"link": "https://link-do-certificado.example.pdf",
"sealing": {
"at": "2024-01-01T00:00:00.000Z",
"state": "SP",
"serie": "ABC123",
"brand": "VDO",
"model": "1381"
},
"rehearsal": {
"state": "SP",
"point": "POSTO EXEMPLO",
"at": "2024-01-01T00:00:00.000Z",
"valid": "2025-01-01T00:00:00.000Z",
"updated": "2024-01-01T00:00:00.000Z",
"standard": "PADRAO",
"read_at": "2024-01-01T00:00:00.000Z"
},
"created_at": "2024-01-15T10:00:00.000Z",
"updated_at": null
}
Bloco car — veículo (estrutura própria deste evento, diferente do car compartilhado)
| Campo | Tipo | Nulo | Descrição |
|---|---|---|---|
id | number | não | ID do veículo na Frota162 — note a chave id, não car_id |
rim | string | sim | Aro da roda |
tire | string | sim | Medida do pneu |
renavam | string | não | RENAVAM do veículo |
plate | string | não | Placa — note a chave plate, não car_plate |
chassi | string | não | Número do chassi |
Bloco gru — Guia de Recolhimento da União (taxa da verificação)
| Campo | Tipo | Nulo | Descrição |
|---|---|---|---|
number | string | sim | Número da GRU |
ammount | string | sim | Valor da taxa — string, não number; grafia com dois m |
payment_at | string | sim | Data/hora do pagamento — ISO-8601 |
Bloco result — certificado emitido
| Campo | Tipo | Nulo | Descrição |
|---|---|---|---|
issue_at | string | sim | Data de emissão do certificado — ISO-8601 |
expiration_at | string | sim | Data de validade do certificado — ISO-8601 |
document | string | sim | Tipo do documento emitido (ex: CERTIFICADO) |
document_number | string | sim | Número do certificado |
responsible | string | sim | Responsável pela emissão |
Bloco sealing — lacração do equipamento
| Campo | Tipo | Nulo | Descrição |
|---|---|---|---|
at | string | sim | Data/hora da lacração — ISO-8601 |
state | string | sim | UF onde a lacração foi feita |
serie | string | sim | Série do lacre |
brand | string | sim | Marca do cronotacógrafo (ex: VDO) |
model | string | sim | Modelo do cronotacógrafo |
Bloco rehearsal — ensaio de aferição no posto autorizado
| Campo | Tipo | Nulo | Descrição |
|---|---|---|---|
state | string | sim | UF do posto de ensaio |
point | string | sim | Nome do posto de ensaio |
at | string | sim | Data/hora do ensaio — ISO-8601 |
valid | string | sim | Validade do ensaio — ISO-8601 |
updated | string | sim | Última atualização do registro do ensaio — ISO-8601 |
standard | string | sim | Padrão do ensaio |
read_at | string | sim | Data/hora da leitura — ISO-8601 |
Campos da raiz
| Campo | Tipo | Nulo | Descrição |
|---|---|---|---|
link | string | sim | URL do certificado em PDF |
updated_at | string | sim | Pode chegar null |
nullDependendo da fonte da consulta, gru, sealing e rehearsal podem chegar com todos os campos em null — os blocos estão sempre presentes, mas o conteúdo depende do que o órgão retornou. Não assuma que sealing.at preenchido implica rehearsal.at preenchido.
Veículo — car
event_id: 9 (dados novos), 10 (atualização) · dispara quando novos dados de um veículo são consultados ou atualizados.
Diferente dos demais eventos, os dados do veículo vêm na raiz do payload — não há bloco car aninhado.
{
"event_type": "car",
"id": 1,
"company_id": 1,
"plate": "ABC1234",
"renavam": "00123456789",
"kind": "AUTOMÓVEL",
"chassi": "9BWZZZ377VT004251",
"state": "SP",
"type": "PASSEIO",
"branding": "TOYOTA",
"model": "COROLLA",
"manufactoryYear": "2023",
"color": "BRANCO",
"result": {
"success": true,
"message": "OK"
}
}
Campos do evento
| Campo | Tipo | Nulo | Descrição |
|---|---|---|---|
id | number | não | ID do veículo na Frota162 |
plate | string | não | Placa do veículo |
renavam | string | sim | RENAVAM |
kind | string | sim | Espécie do veículo (ex: AUTOMÓVEL, CAMINHÃO) |
chassi | string | sim | Número do chassi |
state | string | sim | UF de emplacamento |
type | string | sim | Tipo/categoria (ex: PASSEIO) |
branding | string | sim | Marca (ex: TOYOTA) |
model | string | sim | Modelo (ex: COROLLA) |
manufactoryYear | string | sim | Ano de fabricação — string, não number; grafia manufactoryYear mantida por compatibilidade |
color | string | sim | Cor |
result.success | boolean | não | Se a consulta que originou o evento foi bem-sucedida |
result.message | string | não | Mensagem do resultado da consulta |
created_at/updated_atDiferente dos demais eventos, o payload de veículo não inclui timestamps na raiz. Use o momento do recebimento como referência temporal.
Indicação de condutor — driver_indication
event_id: 11 (API v2) · dispara a cada mudança de status de uma indicação de condutor.
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"driver_id": 12345,
"company_id": 789,
"event_type": "driver_indication",
"status": "confirmed",
"vehicle_type": "CAR",
"signer_type": "OWNER",
"notification_id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
"created_at": "2026-05-14T10:00:00.000Z",
"updated_at": "2026-05-14T10:30:00.000Z"
}
Campos do evento
| Campo | Tipo | Nulo | Descrição |
|---|---|---|---|
id | string (UUID) | não | ID da indicação — use para correlacionar com GET /v2/driver-indications/{id} |
driver_id | number | sim | ID do condutor indicado |
status | string | não | Status atual da indicação, sempre em lowercase (ex.: confirmed, wrong_documents) — lista completa de status |
can_reindicate | boolean | — | Presente apenas quando status = wrong_documents, sempre com valor true: a indicação pode ser corrigida e reenviada. Nos demais status o campo não vem no payload — trate a ausência como false |
vehicle_type | string | sim | Tipo do veículo da indicação |
signer_type | string | sim | Quem assina a indicação (ex: proprietário) |
notification_id | string (UUID) | sim | ID da notificação de infração vinculada |
created_at | string | sim | Criação da indicação — ISO-8601 UTC |
updated_at | string | não | Momento da mudança de status que disparou o evento — ISO-8601 UTC |
Neste evento, can_reindicate pode não vir no payload: o campo só aparece quando status = wrong_documents. Use body.can_reindicate === true em vez de checar só a existência da chave.
Consulte o módulo de Indicação de Motoristas para o fluxo completo e os valores possíveis de cada enum.
Multas administrativas — administrative_frame.*
event_id: 12 · dispara quando uma multa administrativa é registrada ou tem dados alterados.
O corpo é idêntico nos dois eventos — contém sempre o estado completo e atual da multa; o que muda é apenas o event_type. Só geram evento mudanças nos dados que aparecem no payload.
event_type | Dispara quando |
|---|---|
administrative_frame.created | A multa administrativa é registrada |
administrative_frame.updated | Dados da multa mudam (ex.: valor, recurso, condutor, pagamento) |
Neste evento, todos os campos listados estão sempre presentes no payload. Um campo sem valor chega como null — nunca é omitido. Isso vale inclusive para car.car_id (sempre presente, sempre null) e para todos os campos de driver quando não há condutor indicado.
Mapa do payload: raiz (event_type, id, company_id, link, created_at, updated_at) + blocos car · frame · organization · owner · driver · payment · appeal
{
"event_type": "administrative_frame.created",
"id": 123456,
"company_id": 789,
"car": {
"car_id": null,
"car_plate": "ABC1234"
},
"frame": {
"ait": "12345678901",
"ait_original": "12345678900",
"ait_internal": null,
"type": "Infração de trânsito",
"at": "2026-09-01",
"time": "10:30:00",
"expiration_at": "2026-10-15",
"code": "50610",
"description": "Velocidade superior à máxima permitida em até 20%",
"address": "Av. Paulista, 1000",
"city_code": "3550308",
"city": "São Paulo",
"state": "SP",
"points": 5,
"amount": 195.23,
"discount_amount": 156.18,
"driver_indicate": 1
},
"organization": {
"organization_code": "SP001",
"organization_name": "DETRAN-SP"
},
"owner": {
"name": "Empresa Parceira Ltda",
"document": "00.000.000/0001-00"
},
"driver": {
"id": 999,
"indicate": "2026-09-05T14:20:00.000Z",
"name": "João da Silva",
"license": "12345678910",
"identification": "12.345.678-9",
"identification_state": "SP",
"tax_id": "000.000.000-00",
"address": "Rua das Flores, 100",
"address_number": "100",
"addres_zip_code": "01234567",
"distric": "Centro",
"city": "São Paulo",
"state": "SP"
},
"payment": {
"paid": false,
"at": null,
"amount": 0
},
"appeal": {
"status": "NR",
"justify": null
},
"link": "https://boleto.example.com/multas/123456.pdf",
"created_at": "2026-09-01T11:00:00.000Z",
"updated_at": "2026-09-08T17:00:00.000Z"
}
Campos próprios do evento
| Campo | Tipo | Nulo | Descrição |
|---|---|---|---|
id | number | não | ID numérico da multa administrativa na Frota162 (diferente do event_id: 12 de cadastro) |
frame.ait_original | string | sim | AIT original (caso de reautuação) — não existe no evento de multa comum |
frame.ait_internal | string | sim | AIT interno de controle |
owner.name | string | sim | Nome do proprietário do veículo |
owner.document | string | sim | CPF ou CNPJ do proprietário |
appeal.status | string | sim | Status do recurso |
appeal.justify | string | sim | Justificativa do recurso |
link | string | sim | URL do boleto ou documento em PDF |
Objetos compartilhados: car · driver · organization · payment
administrative_frame para o handler de frameO discriminador é propositalmente distinto do evento de multa comum. Em multa administrativa, car_id é sempre null, não existe sne_boleto_status, e há os blocos owner e appeal que não existem em frame. Tratar os dois no mesmo handler gera bugs silenciosos.
Diferenças em relação ao evento frame:
| Aspecto | frame | administrative_frame |
|---|---|---|
car.car_id | preenchido | sempre null |
Bloco owner | não existe | presente |
Bloco appeal | não existe | presente |
sne_boleto_status | presente | não existe |
frame.treated | presente | não existe |
frame.ait_original / ait_internal | não existem | presentes |
driver.indicated_recieve_doc_at / indicated_sent_doc_org_at | presentes | não existem |
| CEP do condutor | address_zip_code | addres_zip_code |