Pular para o conteúdo principal

Webhooks

A Cartrack Fleet API fornece notificações por webhook para permitir que o seu sistema receba atualizações em tempo real para vários eventos. Os webhooks permitem integração contínua ao enviar automaticamente dados de evento para o endpoint especificado sempre que um evento ocorre.

Fluxos de webhook suportados​

Atualmente, a API suporta um conjunto limitado de eventos webhook. Os webhooks não estão disponíveis para todos os eventos do sistema.

Fluxo de webhook atualmente suportado:

  • Bulk Upload Delivery Jobs: acionado quando o processo de criação de jobs é concluído

Neste momento, não existem outros eventos webhook nem outros esquemas de dados suportados. Novos fluxos de webhook poderão ser introduzidos em futuras versões.

Segurança e verificação​

Todos os pedidos webhook enviados pela Cartrack incluem o cabeçalho HTTP X-Webhook-Signature. Esta assinatura permite verificar que o pedido foi realmente enviado pela Cartrack e que não foi adulterado.

A assinatura é gerada com o algoritmo HMAC-SHA256 usando os seguintes componentes:

  • Chave secreta: a sua API key.
  • Payload: o corpo JSON bruto do pedido (como string, antes de qualquer descodificação ou parsing).

Processo de geração da assinatura​

  1. Codifique o payload JSON (conteúdo bruto) como string UTF-8.
  2. Aplique HMAC-SHA256 ao payload usando a sua API key como segredo.

Exemplo (PHP):

$secret = 'your_api_key';
$payload = file_get_contents('php://input');
$signature = hash_hmac('sha256', json_encode($payload), $secret);

if (hash_equals($signature, $_SERVER['X-Webhook-Signature'])) {
    // Pedido verificado
} else {
    // Assinatura inválida
}

Recomenda-se validar sempre a assinatura do webhook antes de processar qualquer pedido, para garantir integridade e segurança dos dados.