Pular para o conteúdo principal
Referência

Webhooks — Eventos e payloads

12 min de leituraVale para v1 · v2

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_idEventoevent_type no payloadPayload
1Nova multa cadastradaframeMultas
2Atualização de multaframeMultas
3Nova notificação cadastradanotificationNotificações
4Atualização de notificaçãonotificationNotificações
5Taxa de IPVADEBITOS-IPVADébitos
6Taxa de DPVATDEBITOS-DPVATDébitos
7Taxa de licenciamentoDEBITOS-LICENCIAMENTODébitos
8CronotacógrafocronotacografoCronotacógrafo
9Dados de veículo novoscarVeículo
10Atualização de dados de veículocarVeículo
11Status de indicação de condutor (API v2)driver_indicationIndicação de condutor
12Multa administrativaadministrative_frame.created · administrative_frame.updatedMultas administrativas

Multas administrativas usam um único cadastro (event_id 12) para criação e atualização; o momento chega no event_type do payload.

Eventos de débito usam UPPERCASE com prefixo 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.

Presença vs. valor nulo

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​

CampoTipoNuloDescrição
car_idnumbersimID do veículo na Frota162. Sempre null em multas administrativas, que não são vinculadas a um veículo cadastrado
car_platestringnãoPlaca 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.

CampoTipoNuloDescrição
idnumbersimID do condutor na Frota162
indicatestringsimData/hora da indicação — ISO-8601 UTC
namestringsimNome do condutor
licensestringsimNúmero da CNH
identificationstringsimRG
identification_statestringsimUF de emissão do RG
tax_idstringsimCPF
addressstringsimLogradouro
address_numberstringsimNúmero do endereço
districstringsimBairro
citystringsimMunicípio
statestringsimUF

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​

CampoTipoNuloDescrição
organization_codenumber | stringsimCódigo do órgão autuador. Chega como number em multas/notificações e como string em multas administrativas
organization_namestringsimNome do órgão autuador

Objeto payment​

CampoTipoNuloDescrição
paidbooleannãoIndica se a multa consta como paga
atstringsimData do pagamento no formato YYYY-MM-DD. null quando não há data registrada
amountnumbernãoValor pago. 0 quando não há valor registrado
paid pode ser true com at: null e amount: 0

Nem 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

CampoTipoNuloDescrição
frame.aitstringnãoNúmero do Auto de Infração de Trânsito
frame.typestringsimTipo da infração
frame.at / frame.timestringsimData (YYYY-MM-DD) e hora (HH:MM:SS) da infração
frame.expiration_atstringsimData de vencimento (YYYY-MM-DD)
frame.codestringsimCódigo da infração no CTB
frame.city_codestringsimCódigo IBGE da cidade
frame.pointsnumbersimPontos na CNH
frame.amount / frame.discount_amountnumbersimValor original e valor com desconto, em reais
frame.driver_indicatenumbernão0 = condutor não indicado, 1 = indicado. Quando 1, o objeto driver vem com valores
frame.treatedbooleannãotrue se o cliente marcou a multa como tratada na plataforma, false caso contrário
linkstringsimLink do boleto
linkFramestringsimLink 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_statusstringsimStatus 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, chega false.
  • Registro novo (event_id 1) sempre chega com false, 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. linkFrame
  • link contém o link do boleto para pagamento; linkFrame contém o link do documento oficial da infração (espelho da multa) — seguindo o mesmo padrão do campo linkNotification no evento notification.
  • null em linkFrame indica 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:

CampoTipoNuloDescrição
notification.indication_limit_atstringsimPrazo-limite para indicar o condutor (YYYY-MM-DD)
notification.treatedbooleannãotrue 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)
linkNotificationstringsimLink 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

CampoTipoNuloDescrição
ammountnumbernãoValor do tributo em reais — grafia com dois m, mantida por compatibilidade
exercisestringnãoAno-exercício do tributo
occurrencestringnãoOcorrência
expedition_atstringsimData de expedição (YYYY-MM-DD)
quotenumbernãoCota/parcela
updated_atnullsempreSempre null — o evento só dispara na criação

Objetos compartilhados: car

updated_at sempre chega null

Eventos 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)

CampoTipoNuloDescrição
idnumbernãoID do veículo na Frota162 — note a chave id, não car_id
rimstringsimAro da roda
tirestringsimMedida do pneu
renavamstringnãoRENAVAM do veículo
platestringnãoPlaca — note a chave plate, não car_plate
chassistringnãoNúmero do chassi

Bloco gru — Guia de Recolhimento da União (taxa da verificação)

CampoTipoNuloDescrição
numberstringsimNúmero da GRU
ammountstringsimValor da taxa — string, não number; grafia com dois m
payment_atstringsimData/hora do pagamento — ISO-8601

Bloco result — certificado emitido

CampoTipoNuloDescrição
issue_atstringsimData de emissão do certificado — ISO-8601
expiration_atstringsimData de validade do certificado — ISO-8601
documentstringsimTipo do documento emitido (ex: CERTIFICADO)
document_numberstringsimNúmero do certificado
responsiblestringsimResponsável pela emissão

Bloco sealing — lacração do equipamento

CampoTipoNuloDescrição
atstringsimData/hora da lacração — ISO-8601
statestringsimUF onde a lacração foi feita
seriestringsimSérie do lacre
brandstringsimMarca do cronotacógrafo (ex: VDO)
modelstringsimModelo do cronotacógrafo

Bloco rehearsal — ensaio de aferição no posto autorizado

CampoTipoNuloDescrição
statestringsimUF do posto de ensaio
pointstringsimNome do posto de ensaio
atstringsimData/hora do ensaio — ISO-8601
validstringsimValidade do ensaio — ISO-8601
updatedstringsimÚltima atualização do registro do ensaio — ISO-8601
standardstringsimPadrão do ensaio
read_atstringsimData/hora da leitura — ISO-8601

Campos da raiz

CampoTipoNuloDescrição
linkstringsimURL do certificado em PDF
updated_atstringsimPode chegar null
Blocos podem chegar com todos os campos null

Dependendo 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

CampoTipoNuloDescrição
idnumbernãoID do veículo na Frota162
platestringnãoPlaca do veículo
renavamstringsimRENAVAM
kindstringsimEspécie do veículo (ex: AUTOMÓVEL, CAMINHÃO)
chassistringsimNúmero do chassi
statestringsimUF de emplacamento
typestringsimTipo/categoria (ex: PASSEIO)
brandingstringsimMarca (ex: TOYOTA)
modelstringsimModelo (ex: COROLLA)
manufactoryYearstringsimAno de fabricação — string, não number; grafia manufactoryYear mantida por compatibilidade
colorstringsimCor
result.successbooleannãoSe a consulta que originou o evento foi bem-sucedida
result.messagestringnãoMensagem do resultado da consulta
Este payload não tem created_at/updated_at

Diferente 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

CampoTipoNuloDescrição
idstring (UUID)nãoID da indicação — use para correlacionar com GET /v2/driver-indications/{id}
driver_idnumbersimID do condutor indicado
statusstringnãoStatus atual da indicação, sempre em lowercase (ex.: confirmed, wrong_documents) — lista completa de status
can_reindicateboolean—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_typestringsimTipo do veículo da indicação
signer_typestringsimQuem assina a indicação (ex: proprietário)
notification_idstring (UUID)simID da notificação de infração vinculada
created_atstringsimCriação da indicação — ISO-8601 UTC
updated_atstringnãoMomento da mudança de status que disparou o evento — ISO-8601 UTC
Exceção ao contrato de presença

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_typeDispara quando
administrative_frame.createdA multa administrativa é registrada
administrative_frame.updatedDados da multa mudam (ex.: valor, recurso, condutor, pagamento)
Contrato de presença: campo presente e nulo, nunca ausente

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

CampoTipoNuloDescrição
idnumbernãoID numérico da multa administrativa na Frota162 (diferente do event_id: 12 de cadastro)
frame.ait_originalstringsimAIT original (caso de reautuação) — não existe no evento de multa comum
frame.ait_internalstringsimAIT interno de controle
owner.namestringsimNome do proprietário do veículo
owner.documentstringsimCPF ou CNPJ do proprietário
appeal.statusstringsimStatus do recurso
appeal.justifystringsimJustificativa do recurso
linkstringsimURL do boleto ou documento em PDF

Objetos compartilhados: car · driver · organization · payment

Não roteie administrative_frame para o handler de frame

O 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:

Aspectoframeadministrative_frame
car.car_idpreenchidosempre null
Bloco ownernão existepresente
Bloco appealnão existepresente
sne_boleto_statuspresentenão existe
frame.treatedpresentenão existe
frame.ait_original / ait_internalnão existempresentes
driver.indicated_recieve_doc_at / indicated_sent_doc_org_atpresentesnão existem
CEP do condutoraddress_zip_codeaddres_zip_code

Próximos passos​