A), em andamento (E) ou em espera (S).
ℹ️ Limite de cadastro: é possível cadastrar até 5 webhooks por tipo, para cada combinação de central, empresa e responsável.
⚠️ 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 envia a posição dos condutores que estão com solicitações em espera (S), em andamento (E) ou aceitas (A). O envio é feito em lote: a cada 10 segundos a Machine agrupa a posição mais recente de cada condutor e faz uma requisição POST na URL cadastrada.
Exemplo do Payload
Campos do envelope
Campos de cada item de data
As duas datas do payload
O payload carrega dois relógios diferentes:datetime(envelope) -> quando a Machine montou e enviou o lote.timestamp(item) -> quando a posição foi gerada pelo condutor. É o campo a usar para ordenar posições e calcular a idade da leitura.
Variação conforme o responsável do webhook
Como consumir
- Deduplique por
event_id. Uma janela com mais de 500 posições é dividida em várias requisições, cada uma com o seu próprioevent_ide o mesmodatetime. - Um item por condutor e solicitação por janela. Dentro dos 10 segundos, só a posição mais recente de cada par condutor/solicitação é enviada. Um condutor com duas solicitações ativas gera dois itens.
- Não há reenvio. Se a sua URL responder erro ou não responder, o lote não é reentregue — a janela seguinte já traz uma posição mais nova.
- Posições antigas não são entregues. Uma leitura com mais de 15 segundos é descartada, para que você nunca receba uma posição que já não representa o condutor.
- Trate campos desconhecidos com tolerância. Campos novos podem ser acrescentados ao item sem aviso.
(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
Exemplo de apresentação do status_label
Enum de Status
Como usar
status_code: valor curto do statusstatus_label: valor descritivo do status- Extensibilidade: se a Machine adicionar novos status no futuro, basta incluir novos pares para
codes/label
Campos
Links no Payload
links.request-> acesso aos detalhes da solicitaçãolinks.enterprise-> (opcional) referência à empresalinks.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 nas conversas com a central, garantindo histórico e rastreabilidade da comunicação. As mensagens da conversa entre condutor e passageiro durante a corrida não passam por ele: são entregues pelo Webhook de Mensagens da Corrida.Exemplo do Payload
Campos
Enum type_code
Webhook de Mensagens da Corrida
O Webhook de Mensagens da Corrida é acionado sempre que o condutor ou o passageiro envia uma mensagem no chat de uma corrida. É um tipo próprio de webhook,mensagens_corrida: quem já recebe o Webhook de Mensagens continua recebendo só as conversas da central, e passa a receber a conversa da corrida apenas se cadastrar este tipo.
As mensagens de uma mesma corrida chegam na ordem em que foram escritas, uma requisição por mensagem. Apenas a central cadastra este tipo; o cadastro não está disponível para usuários de empresa.
Exemplo do Payload
Campos
Enum sender_type
Enum type_code
(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.(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.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 campoSignature-V2 é composto pelos elementos enviados no webhook, a função de hash SHA-512 e a chave da API.
No webhook de posição, a Signature-V2 é calculada sobre o corpo inteiro da requisição — o envelope com o array data —, e não sobre cada posição.
É 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.