Webhooks

Webhooks enviam notificacoes HTTP em tempo real quando eventos ocorrem na sua frota. Receba atualizacoes instantaneas para corridas, mudancas de status de veiculos, acoes de clientes e mais.

Visao Geral

O Que Webhooks Fazem

Em vez de consultar a API, webhooks enviam atualizacoes para voce:

Evento ocorre → Levy envia POST HTTP → Seu servidor recebe dados

Casos de Uso

• Dashboards em tempo real
• Sistemas de alerta externos
• Sincronizacao de dados
• Integracoes de faturamento
• Plataformas de analytics
• Notificacoes personalizadas

Configurando Webhooks

Criar Endpoint de Webhook

1. Navegue ate Configuracoes > Webhooks
2. Clique em Adicionar Webhook
3. Configure:
   • URL do endpoint
   • Eventos a receber
   • Segredo (para verificacao)
4. Clique em Criar

Opcoes de Configuracao

Requisitos de URL

Seu endpoint deve:

• Usar HTTPS
• Retornar resposta 2xx
• Responder em ate 30 segundos
• Aceitar requisicoes POST
• Processar corpo JSON

Eventos Disponiveis

Eventos de Corridas

Eventos de Veiculos

Eventos de Clientes

Eventos de Pagamento

Eventos de IoT

Payload do Evento

Estrutura Padrao

Todos os eventos incluem:

{
  "id": "evt_abc123",
  "type": "ride.ended",
  "created": "2025-12-25T10:30:00Z",
  "data": {
    // Dados especificos do evento
  },
  "account_id": "acc_xyz789"
}

Exemplo: Corrida Finalizada

{
  "id": "evt_abc123",
  "type": "ride.ended",
  "created": "2025-12-25T10:30:00Z",
  "data": {
    "ride_id": "ride_456",
    "customer_id": "cust_789",
    "vehicle_id": "veh_012",
    "duration_minutes": 15,
    "distance_km": 2.5,
    "fare": 5.50,
    "start_location": {
      "lat": -23.5505,
      "lng": -46.6333
    },
    "end_location": {
      "lat": -23.5605,
      "lng": -46.6433
    }
  }
}

Exemplo: Status de Veiculo Alterado

{
  "id": "evt_def456",
  "type": "vehicle.status_changed",
  "created": "2025-12-25T11:00:00Z",
  "data": {
    "vehicle_id": "veh_012",
    "vehicle_number": "LV-001",
    "previous_status": "available",
    "new_status": "in_use",
    "battery_level": 85,
    "location": {
      "lat": -23.5505,
      "lng": -46.6333
    }
  }
}

Verificando Webhooks

Verificacao de Assinatura

Cada webhook inclui um cabecalho de assinatura:

X-Levy-Signature: t=1640000000,v1=abc123...

Passos de Verificacao

1. Extraia timestamp e assinatura
2. Construa payload assinado
3. Calcule assinatura esperada
4. Compare assinaturas

Exemplo (Node.js)

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const [t, v1] = signature.split(',');
  const timestamp = t.split('=')[1];
  const sig = v1.split('=')[1];

  const signedPayload = `${timestamp}.${payload}`;
  const expected = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex');

  return sig === expected;
}

Validacao de Timestamp

Previna ataques de replay:

• Verifique se timestamp e recente (< 5 minutos)
• Rejeite webhooks antigos

Tratando Webhooks

Requisitos de Resposta

Seu endpoint deve:

• Retornar status 200-299
• Responder rapidamente (< 30s)
• Processar de forma assincrona se demorado

Politica de Retry

Entregas falhadas sao reenviadas:

Apos 5 falhas, webhook e pausado.

Idempotencia

Eventos podem ser entregues multiplas vezes:

• Use id do evento para deduplicar
• Faca handlers idempotentes
• Armazene IDs de eventos processados

Gerenciando Webhooks

Visualizando Webhooks

A pagina de Webhooks mostra:

• Todos os webhooks configurados
• Inscricoes de eventos
• Status de entrega
• Hora da ultima entrega

Testando Webhooks

Envie eventos de teste:

1. Clique no webhook
2. Clique em Enviar Teste
3. Selecione tipo de evento
4. Veja resultado da entrega

Visualizando Logs de Entrega

Veja historico de entregas:

• Timestamp
• Tipo de evento
• Status da resposta
• Corpo da resposta
• Tentativas de retry

Desabilitando Webhooks

Para pausar entregas:

1. Clique no webhook
2. Desative Ativo
3. Eventos sao enfileirados (ate 24h)

Excluindo Webhooks

Para remover:

1. Clique no webhook
2. Clique em Excluir
3. Confirme exclusao

Filtragem de Eventos

Por Tipo de Evento

Selecione eventos especificos:

• Todos os eventos
• Apenas eventos de corridas
• Apenas eventos de veiculos
• Selecao personalizada

Por Subconta

Filtre por localizacao:

• Todas as subcontas
• Subcontas especificas
• Subconta unica

Por Condicoes

Filtragem avancada:

• Modelo de veiculo
• Mudancas de status
• Valores de limite

Melhores Praticas

Design do Endpoint

• Use endpoint dedicado para webhooks
• Retorne 200 imediatamente
• Processe de forma assincrona
• Registre todas as entregas

Tratamento de Erros

• Trate payloads malformados
• Sempre verifique assinaturas
• Implemente tratamento de timeout
• Alerte sobre falhas repetidas

Seguranca

• Use apenas HTTPS
• Verifique assinaturas
• Valide timestamps
• Use rotacao de segredos

Escalabilidade

• Use filas de mensagens
• Trate rajadas graciosamente
• Escale endpoint conforme necessario
• Monitore latencia

Cenarios de Webhook

Dashboard em Tempo Real

Evento: ride.started → Atualiza contagem de corridas ativas
Evento: ride.ended → Calcula receita
Evento: vehicle.status_changed → Atualiza mapa

Sistema de Alertas

Evento: vehicle.low_battery → Alerta equipe de ops
Evento: vehicle.offline → Cria ticket
Evento: iot.alarm → Dispara notificacao

Pipeline de Analytics

Todos os eventos → Fila de mensagens → Processador de analytics → Banco de dados

Solucao de Problemas

Webhooks Nao Recebidos

1. Verifique se endpoint esta acessivel
2. Verifique se webhook esta ativo
3. Revise selecao de eventos
4. Verifique logs do servidor

Verificacao de Assinatura Falhou

1. Verifique se segredo esta correto
2. Verifique parsing do payload
3. Valide tratamento de timestamp
4. Revise implementacao

Entregas Falhando

1. Verifique se endpoint retorna 2xx
2. Verifique se tempo de resposta < 30s
3. Revise erros do servidor
4. Verifique regras de firewall

Eventos Duplicados

1. Implemente deduplicacao
2. Use rastreamento de ID de evento
3. Faca handlers idempotentes
4. Verifique timing de retry

---