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 a webhook event for every meaningful status change across the shipment lifecycle that GET /api/v1/track and /api/v1/events report. Each delivery carries the event name, a timestamp, and a data object with the shipment context for that event. The stages below are the lifecycle milestones; the literal event string your endpoint receives may be Warp's internal status code (the tracking API surfaces codes such as needCarrier), so switch on it and confirm the exact values by firing POST /api/v1/developer/webhook/test or reading GET /api/v1/events.

Webhook payload: the envelope

Every delivery is a plain JSON POST with three fields: event (the milestone name), timestamp (when it happened), and data (the shipment context for that event). There is no signature header — deliveries are unsigned today, which is why your registered URL should carry an unguessable secret. Don't integrate against an example payload: fire POST /api/v1/developer/webhook/test and build against the exact data shape your endpoint receives.

{
  "event": "delivered",
  "timestamp": "2026-08-17T14:22:00Z",
  "data": {
    // Shipment context for the event. Inspect the exact
    // shape your account receives:
    //   POST /api/v1/developer/webhook/test
  }
}

Exception events

Our AI backbone, Orbit, monitors every shipment in real time. When Orbit detects a risk — a late pickup, a missed scan window, a delay at the cross dock — an exception event arrives through the same envelope, before the problem becomes a missed delivery. In many cases Warp ops is already re-planning the load by the time your system receives the event; tracking carries the revised ETA.

Setting up a webhook listener

Webhooks are available on self-serve. First, sign in once at /agents/account to link your Warp account — this is required before the API can manage your webhook, and calls made before it return 409 WARP_SESSION_REQUIRED. Then register your webhook URL with POST /api/v1/developer/webhook — or skip the API and add it in the dashboard: sign in at customer.wearewarp.com, open Settings, and paste your URL into the Webhook URLfield under API Access. Either way your endpoint then receives a POST request for every event. Deliveries are not signed today — put an unguessable secret in your registered URL and reject requests that lack it. Respond with a 2xx promptly and do the heavy work after you've acknowledged. Here is a minimal Express.js listener that routes events by type.

// Express.js webhook listener — deliveries are unsigned,
// so the unguessable path segment IS the authentication
const express = require('express');
const app = express();
app.use(express.json());

app.post('/webhooks/warp/:secret', (req, res) => {
  if (req.params.secret !== process.env.WARP_WEBHOOK_PATH_SECRET) {
    return res.status(404).end();
  }

  // Envelope: { event, timestamp, data }
  const { event, timestamp, data } = req.body;

  switch (event) {
    case 'pickupSuccessful':
      // Update your TMS: shipment picked up, BOL available
      updateShipmentStatus(data, 'picked_up');
      break;

    case 'delivered':
      // Close out the order, trigger invoicing
      markDelivered(data);
      break;

    case 'exception':
      // Alert your ops team
      notifyOpsTeam(data);
      break;

    default:
      // Log every other milestone for the audit trail
      logEvent(event, timestamp, data);
  }

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

app.listen(3000);

What you can build with webhook events

Reliability: push plus a pollable source of truth

Treat webhooks as the real-time push and the API as the system of record. Every status change is persisted on the Warp side regardless of webhook delivery, so if your endpoint is down or misses a delivery, nothing is lost — pull the full event history any time from GET /api/v1/events or the current status from GET /api/v1/track. Build your handler idempotent so a duplicate delivery is harmless.

• -Every status change is persisted server-side. Nothing is lost if your endpoint is temporarily down.
• -Fallback: GET /api/v1/events returns the full event history at any time; GET /api/v1/track returns current status.
• -Acknowledge fast: respond 2xx promptly and queue the heavy work.
• -Be idempotent: dedupe on event + timestamp so a duplicate delivery is a no-op.
• -Verify your endpoint before going live: POST /api/v1/developer/webhook/test fires a test delivery.

Frequently asked questions