Real Time Freight Events, Not Check Calls

Polling, check calls, EDI, and webhooks

Most freight tracking relies on one of three approaches: polling the carrier API every few minutes, calling the carrier for status updates, or waiting for batched EDI 214 messages. All three introduce delay. Webhooks flip the model. Warp pushes events to your system the moment they happen.

Event types

Warp fires webhook events for every meaningful status change in the shipment lifecycle. Each event includes a timestamp, GPS coordinates, and contextual data specific to the event type. Your system receives them in the order they happen.

Webhook payload: DELIVERED

When freight is delivered, your webhook endpoint receives a payload with GPS coordinates, the name of the person who signed, photo count, a link to the proof of delivery, and delivery notes. Everything you need to close out the order automatically.

{
  "event": "DELIVERED",
  "shipmentId": "shp_01HGA2K9MNPQ4RV8XW3YZ5TJ6",
  "trackingNumber": "WARP1234567890",
  "orderId": "ord_01HGA2K9MNPQ4RV8XW3YZ5TK7",
  "timestamp": "2025-03-17T14:22:00Z",
  "location": {
    "latitude": 33.4484,
    "longitude": -112.0740,
    "city": "Phoenix",
    "state": "AZ"
  },
  "details": {
    "signedBy": "J. Martinez",
    "photoCount": 2,
    "podUrl": "https://api.wearewarp.com/pod/abc123",
    "deliveryNotes": "Left at receiving dock B"
  }
}

Webhook payload: EXCEPTION

Our AI backbone, Orbit, monitors every shipment in real time. When Orbit detects a risk, it fires an EXCEPTION event before the problem becomes a missed delivery. The payload includes exception type, severity, a description of the issue, and a suggested action. In many cases, Warp is already resolving the issue by the time your system receives the event.

{
  "event": "EXCEPTION",
  "shipmentId": "shp_01HGA2K9MNPQ4RV8XW3YZ5TJ6",
  "trackingNumber": "WARP1234567890",
  "timestamp": "2025-03-17T06:15:00Z",
  "location": {
    "latitude": 34.0522,
    "longitude": -118.2437,
    "city": "Los Angeles",
    "state": "CA"
  },
  "exception": {
    "type": "LATE_PICKUP_RISK",
    "severity": "warning",
    "message": "Driver ETA is 45 min past pickup window",
    "suggestedAction": "Warp is dispatching backup driver",
    "flaggedBy": "Orbit"
  }
}

Setting up a webhook listener

Register your webhook URL in the Warp dashboard under developer settings. Your endpoint receives a POST request for every event. Return a 200 status within 5 seconds. Here is a minimal Express.js listener that routes events by type.

// Express.js webhook listener
const express = require('express');
const app = express();
app.use(express.json());

app.post('/webhooks/warp', (req, res) => {
  const event = req.body;

  switch (event.event) {
    case 'PICKED_UP':
      // Update your TMS: shipment in transit
      updateShipmentStatus(event.shipmentId, 'picked_up');
      break;

    case 'DELIVERED':
      // Close out the order, trigger invoicing
      markDelivered(event.shipmentId, event.details);
      break;

    case 'EXCEPTION':
      // Alert your ops team
      notifyOpsTeam(event.shipmentId, event.exception);
      break;

    default:
      // Log all other events for audit trail
      logEvent(event);
  }

  res.status(200).send('OK');
});

app.listen(3000);

What you can build with webhook events

Reliability and retries

Warp retries failed webhook deliveries with exponential backoff for up to 24 hours. If your endpoint returns a non 200 status or times out, the event is queued and retried at increasing intervals. You can also pull any missed events from the tracking endpoint (GET /freights/events/{shipmentId}) as a fallback. Every event is persisted on the Warp side regardless of webhook delivery status.

• -First retry: 30 seconds after initial failure.
• -Subsequent retries: exponential backoff up to 1 hour intervals.
• -Total retry window: 24 hours.
• -Fallback: GET /freights/events/{shipmentId} returns the full event history at any time.
• -Every event is persisted. Nothing is lost if your endpoint is temporarily down.

Frequently asked questions