Um webhook é uma forma de recebimento de informações quando ocorre um dado evento. Neste caso, quando uma solicitação sofrer uma alteração do seu estado, a Machine irá acionar uma URL informada pela central com determinadas informações sobre a solicitação que sofreu a mudança. O nosso webhook do tipo status envia eventos nos seguintes momentos: quando uma solicitação muda de status, quando o condutor sinaliza que chegou ao local e quando uma parada é confirmada. As informações enviadas vão variar conforme o estado da solicitação. Por exemplo, enquanto a solicitação não foi aceita, nenhum dado associado ao aceite será enviado, entretanto, quando ela for aceita, as informações associadas ao aceite serão enviadas. O nosso webhook do tipo posição envia a posição dos condutores que estão com solicitações aceitas (A), em andamento (E) ou em espera (S).

ℹ️ Limite de cadastro: é possível cadastrar até 5 webhooks por tipo. O webhook do tipo mensagem é limitado a 1 cadastro.

⚠️ Atenção: Os antigos formatos dos Webhooks de Status e Posição serão deprecados. A central deve cadastrar novamente os webhooks para utilizar os novos formatos.

(Novo) Webhook de Posição

O Webhook de Posição realiza o envio da posição de condutores, a cada 15s, que estão com solicitações em espera (S), em andamento (E) ou aceitas (A).

Exemplo do Payload

{
 "datetime": "2025-08-29T13:20:05Z",
 "event_id": "550e8400-e29b-41d4-a716-446655440000",
 "company_id": 8,
 "request_id": 12345,
 "driver_id": 8101,
 "latitude": -22.906847,
 "longitude": -43.172896,
 "links": {
   "request": "https://api.taximachine.com.br/api/v1/request/12345",
   "driver": "https://api.taximachine.com.br/api/integracao/condutor?id=8101",
   "enterprise": "https://api.taximachine.com.br/api/integracao/empresa?empresa_id=987"
 }
}

Campos

Campo	Formato	Requerido	Descrição
`datetime`	ISO-8601	SIM	Data e hora do evento gerado pela Machine.
`event_id`	UUID	SIM	Identificação única do evento (idempotência).
`company_id`	INT	SIM	Identificador da central.
`request_id`	INT	SIM	Identificador da solicitação.
`driver_id`	INT	SIM	Identificador do condutor na plataforma Machine.
`latitude`	DECIMAL	SIM	Latitude do condutor.
`longitude`	DECIMAL	SIM	Longitude do condutor.
`links`	Object	SIM	URLs relacionadas ao evento. Inclui sempre `request` e `driver`.

Links no Payload

links.request -> acesso aos detalhes da solicitação.
links.driver -> referência ao condutor.
links.enterprise -> (opcional) referência à empresa vinculada.

(Novo) Webhook de Status

O Webhook de Status é acionado sempre que uma solicitação passa por uma mudança de estado (ex.: aceita, em andamento, finalizada, cancelada), quando o condutor indica chegada ao local ou quando uma parada é confirmada.

Exemplo do Payload

{
 "datetime": "2025-08-29T13:20:05Z",
 "event_id": "550e8400-e29b-41d4-a716-446655440000",
 "company_id": 8,
 "request_id": 12345,
 "status_code": "A",
 "status_label": "ACEITA",
 "stop_id": 567,
 "links": {
   "request": "https://api.taximachine.com.br/api/v1/request/12345",
   "driver": "https://api.taximachine.com.br/api/integracao/condutor?id=321",
   "enterprise": "https://api.taximachine.com.br/api/integracao/empresa?empresa_id=987"
 }
}

Exemplo de apresentação do `status_label`

Enum de Status

Código (`status_code`)	Label (`status_label`)	Descrição
`AP`	`ARRIVED_AT_LOCATION`	Condutor chegou ao local
`ER`	`STOP_FINISHED`	Parada finalizada
`L`	`WAITING_RELEASE`	Aguardando liberação
`R`	`WAITING_PAYMENT`	Aguardando pagamento
`D`	`DISTRIBUTING`	Distribuindo
`G`	`WAITING_ACCEPTANCE`	Aguardando aceite
`P`	`PENDING`	Pendente
`S`	`ON_HOLD`	Solicitação em espera
`N`	`NOT_SERVED`	Solicitação não atendida ou buscando condutor
`A`	`ACCEPTED`	Solicitação aceita
`E`	`IN_PROGRESS`	Solicitação em andamento
`C`	`CANCELLED`	Solicitação cancelada
`F`	`FINISHED`	Solicitação finalizada
`U`	`GROUPED`	Solicitação agrupada em andamento

Como usar

status_code: valor curto do status
status_label: valor descritivo do status
Extensibilidade: se a Machine adicionar novos status no futuro, basta incluir novos pares para codes/label

Campos

Campo	Formato	Requerido	Descrição
`datetime`	ISO-8601	SIM	Data e hora do evento gerado pela Machine.
`event_id`	UUID	SIM	Identificação única do evento (idempotência).
`company_id`	INT	SIM	Identificador da central
`request_id`	INT	SIM	Identificador da solicitação
`status_code`	VARCHAR(2)	SIM	Código do status
`status_label`	ENUM	SIM	Status descritivo
`stop_id`	INT	NÃO	Identificador da parada (preenchido apenas no status `STOP_FINISHED`)
`links`	Object	SIM	URLs relacionadas ao evento. Inclui sempre `request` e pode incluir `enterprise` e `driver` (se aplicável)

Links no Payload

links.request -> acesso aos detalhes da solicitação
links.enterprise -> (opcional) referência à empresa
links.driver -> (opcional) referência ao condutor

Webhook de Mensagens

O Webhook de Mensagens é acionado sempre que ocorre o recebimento de mensagens relacionadas a uma central. Ele possibilita à central receber as mensagens enviadas pelo condutor e empresa, garantindo histórico e rastreabilidade da comunicação.

Exemplo do Payload

{
 "company_id": 8,
 "content": "me aguarde",
 "datetime": "2025-08-29T14:01:36Z",
 "event_id": "0198f622-400f-7137-a03d-142dd9c2298a",
 "message_id": 24148,
 "sender_id": 8101,
 "sequence": 1,
 "type_code": "DRIVER",
 "type_label": "P",
 "links": {
   "sender": "https://api.taximachine.com.br/api/integracao/condutor?id=8101"
 }
}

Campos

Campo	Formato	Requerido	Descrição
`datetime`	ISO-8601	SIM	Data e hora do evento gerado pela Machine.
`event_id`	UUID	SIM	Identificação única do evento (idempotência).
`company_id`	INT	SIM	Identificador da central
`message_id`	INT	SIM	Identificador da mensagem
`sender_id`	INT	SIM	Identificador do remetente (condutor, empresa)
`sequence`	INT	SIM	Número sequencial da mensagem no contexto da solicitação
`type_code`	ENUM	SIM	Origem da mensagem ( `DRIVER`, `ENTERPRISE`)
`type_label`	String	SIM	Indicação adicional do tipo de mensagem (pode variar por contexto)
`content`	String	SIM	Conteúdo textual da mensagem
`links`	Object	SIM	URLs relacionadas ao evento. Inclui, por exemplo, a referência ao remetente ( `sender`)

Enum `type_label`

Code	Label	Descrição
`P`	`DRIVER`	Chat do tipo condutor
`E`	`ENTERPRISE`	Chat do tipo empresa

(DEPRECADO) Webhook de Posição

O webhook de posição realiza o envio de posição de condutores, a cada 15s, que estão com solicitações em espera (S), em andamento (E) ou aceitas (A). Caso a central configuração e de corrida sejam a mesma, a central receberá o evento do webhook apenas uma vez.

Campo	Formato	Descrição
`id_mch`	String (Obrigatório)	Identificação da corrida no Sistema Machine
`condutor_id`	String	Identificação do condutor
`lat_cond`	String (Obrigatório)	Latitude do condutor
`lng_cond`	String (Obrigatório)	Longitude do condutor

(DEPRECADO) Webhook de Mudança de Status

Um webhook é uma forma de recebimento de informações quando ocorre um dado evento. Neste caso, quando uma corrida sofrer uma alteração do seu estado, quando uma parada for confirmada ou quando o condutor indicar que chegou ao local, a Machine irá acionar uma URL informada pela central com determinadas informações. Este é um mecanismo prático para receber dados da Machine. Caso a central configuração e de corrida sejam a mesma, a central receberá o evento do webhook apenas uma vez.

Campo	Formato	Descrição
`id_mch`	String (Obrigatório)	Identificação da solicitação no Sistema Machine
`id_externo`	String	Identificação da solicitação pela central
`status_solicitacao`	String (Obrigatório)	Status da solicitação.
`data_hora_solicitacao`	Datetime (Obrigatório)	Data e hora de abertura da solicitação
`chave_trajeto`	String (Obrigatório)	Chave para acesso a consulta aos trajetos
`usuario`	String	Nome do usuário de abertura da solicitação
`condutor`		(Bloco opcional) - usado apenas quando o condutor atender a solicitação
`id`	Integer (Obrigatório)	Identificação do condutor na plataforma machine
`nome`	String (Obrigatório)	Nome do condutor
`vtr`	String (Obrigatório)	Número da viatura no cadastro do condutor
`telefone`	String (Obrigatório)	Telefone do cadastro do condutor
`cpf`	String (Obrigatório)	CPF do condutor
`modelo`	String (Obrigatório)	Modelo do veículo
`placa`	String (Obrigatório)	Placa do veículo
`empresa`		(Bloco opcional) - usado para solicitação em eTicket ou Voucher
`nome`	String (Obrigatório)	Nome da empresa
`centro_custo`	String	Nome do centro de custo
`serie_voucher`	String (Obrigatório)	Série do voucher
`numero_voucher`	String (Obrigatório)	Número do voucher
`status_ticket`	String (Obrigatório)	Status de autorização do eTicket.
`numero_autorizacao`	Number (Obrigatório)	Número de autorização
`data_hora_autorizacao`	Datetime (Obrigatório)	Data e hora da autorização
`tipo_finalizacao`	String (Obrigatório)	Tipo de finalização do eTicket
`andamento`		(Bloco opcional) - usado para andamento da solicitação

Assinatura de validação do Webhook

A assinatura de validação do webhook tem como objetivo garantir a integridade e a autenticação da mensagem. Os campos de assinatura, contidos no HEADER, seguem o padrão HMAC-SHA-512. O campo Signature-V2 é composto pelos elementos enviados no webhook, a função de hash SHA-512 e a chave da API. É importante observar que o campo Signature está atualmente obsoleto, sendo substituído pelo Signature-V2; no entanto, ele é construído com base nos dados recebidos no webhook, a função de hash SHA-512 e a chave privada previamente informada.

Content-Type: application/json
Signature-V2: 17d3170aa2271f8ce1151f730cfea1660359f073e99bc96c2320a49a23bf0700225017c3135693eb7bd1ba9aa06ada60924fdf38f2856bd3ef3aca169f89988a
@deprecated Signature: 17d3170aa2271f8ce1151f730cfea1660359f073e99bc96c2320a49a23bf0700225017c3135693eb7bd1ba9aa06ada60924fdf38f2856bd3ef3aca169f89988a

Introdução

Cupons

Central

Saque automático

Dinâmica

Entregador

Webhooks

Categorias

Solicitação

Empresa

Sobre

(Novo) Webhook de Posição

Exemplo do Payload

Campos

Links no Payload

(Novo) Webhook de Status

Exemplo do Payload

Exemplo de apresentação do `status_label`

Enum de Status

Como usar

Campos

Links no Payload

Webhook de Mensagens

Exemplo do Payload

Campos

Enum `type_label`

(DEPRECADO) Webhook de Posição

(DEPRECADO) Webhook de Mudança de Status

Assinatura de validação do Webhook

​(Novo) Webhook de Posição

​Exemplo do Payload

​Campos

​Links no Payload

​(Novo) Webhook de Status

​Exemplo do Payload

​Exemplo de apresentação do status_label

​Enum de Status

​Como usar

​Campos

​Links no Payload

​Webhook de Mensagens

​Exemplo do Payload

​Campos

​Enum type_label

​(DEPRECADO) Webhook de Posição

​(DEPRECADO) Webhook de Mudança de Status

​Assinatura de validação do Webhook

(Novo) Webhook de Posição

Exemplo do Payload

Campos

Links no Payload

(Novo) Webhook de Status

Exemplo do Payload

Exemplo de apresentação do `status_label`

Enum de Status

Como usar

Campos

Links no Payload

Webhook de Mensagens

Exemplo do Payload

Campos

Enum `type_label`

(DEPRECADO) Webhook de Posição

(DEPRECADO) Webhook de Mudança de Status

Assinatura de validação do Webhook