Webhooks

Webhooks send real-time HTTP notifications when events occur in your fleet. Receive instant updates for rides, vehicle status changes, customer actions, and more.

Overview

What Webhooks Do

Instead of polling the API, webhooks push updates to you:

Event occurs → Levy sends HTTP POST → Your server receives data

Use Cases

• Real-time dashboards
• External alerting systems
• Data synchronization
• Billing integrations
• Analytics platforms
• Custom notifications

Setting Up Webhooks

Create Webhook Endpoint

1. Navigate to Settings > Webhooks
2. Click Add Webhook
3. Configure:
   • Endpoint URL
   • Events to receive
   • Secret (for verification)
4. Click Create

Configuration Options

URL Requirements

Your endpoint must:

• Use HTTPS
• Return 2xx response
• Respond within 30 seconds
• Accept POST requests
• Handle JSON body

Available Events

Ride Events

Vehicle Events

Customer Events

Payment Events

IoT Events

Event Payload

Standard Structure

All events include:

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

Example: Ride Ended

{
  "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": 40.7128,
      "lng": -74.0060
    },
    "end_location": {
      "lat": 40.7200,
      "lng": -74.0100
    }
  }
}

Example: Vehicle Status Changed

{
  "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": 40.7128,
      "lng": -74.0060
    }
  }
}

Verifying Webhooks

Signature Verification

Each webhook includes a signature header:

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

Verification Steps

1. Extract timestamp and signature
2. Construct signed payload
3. Compute expected signature
4. Compare signatures

Example (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;
}

Timestamp Validation

Prevent replay attacks:

• Check timestamp is recent (< 5 minutes)
• Reject old webhooks

Handling Webhooks

Response Requirements

Your endpoint should:

• Return 200-299 status
• Respond quickly (< 30s)
• Process asynchronously if slow

Retry Policy

Failed deliveries are retried:

After 5 failures, webhook is paused.

Idempotency

Events may be delivered multiple times:

• Use event id to deduplicate
• Make handlers idempotent
• Store processed event IDs

Managing Webhooks

Viewing Webhooks

The Webhooks page shows:

• All configured webhooks
• Event subscriptions
• Delivery status
• Last delivery time

Testing Webhooks

Send test events:

1. Click on webhook
2. Click Send Test
3. Select event type
4. View delivery result

Viewing Delivery Logs

See delivery history:

• Timestamp
• Event type
• Response status
• Response body
• Retry attempts

Disabling Webhooks

To pause deliveries:

1. Click on webhook
2. Toggle Active off
3. Events queue (up to 24h)

Deleting Webhooks

To remove:

1. Click on webhook
2. Click Delete
3. Confirm deletion

Event Filtering

By Event Type

Select specific events:

• All events
• Ride events only
• Vehicle events only
• Custom selection

By Subaccount

Filter by location:

• All subaccounts
• Specific subaccounts
• Single subaccount

By Conditions

Advanced filtering:

• Vehicle model
• Status changes
• Threshold values

Best Practices

Endpoint Design

• Use dedicated webhook endpoint
• Return 200 immediately
• Process asynchronously
• Log all deliveries

Error Handling

• Handle malformed payloads
• Verify signatures always
• Implement timeout handling
• Alert on repeated failures

Security

• Use HTTPS only
• Verify signatures
• Validate timestamps
• Use secret rotation

Scalability

• Use message queues
• Handle bursts gracefully
• Scale endpoint as needed
• Monitor latency

Webhook Scenarios

Real-Time Dashboard

Event: ride.started → Update live ride count
Event: ride.ended → Calculate revenue
Event: vehicle.status_changed → Update map

Alert System

Event: vehicle.low_battery → Alert ops team
Event: vehicle.offline → Create ticket
Event: iot.alarm → Trigger notification

Analytics Pipeline

All events → Message queue → Analytics processor → Database

Troubleshooting

Webhooks Not Received

1. Verify endpoint is accessible
2. Check webhook is active
3. Review event selection
4. Check server logs

Signature Verification Failed

1. Verify secret is correct
2. Check payload parsing
3. Validate timestamp handling
4. Review implementation

Deliveries Failing

1. Check endpoint returns 2xx
2. Verify response time < 30s
3. Review server errors
4. Check firewall rules

Duplicate Events

1. Implement deduplication
2. Use event ID tracking
3. Make handlers idempotent
4. Check retry timing

---