Logistics API with Webhooks: Why Polling Is Slowing Down Your

If your logistics dashboard still polls for order statuses every few seconds, you are paying for delays, extra server load, and a worse customer experience. A logistics API with webhooks flips the model: instead of asking "what changed?" over and over, the system tells you the moment something happens. For merchants and fulfillment centers coordinating orders across riders and customers, this means faster updates, fewer missed events, and a cleaner integration. This guide explains how webhooks work, how to secure them with HMAC signatures, and how to handle retries and failures without losing data.

Why Polling Is Killing Your Dashboard

Polling is the old way: your system hits the API every 30 seconds or every minute to check if an order status changed. Each request costs time and bandwidth, and you still end up with a dashboard that lags behind reality. If a rider marks a delivery complete, your customer might not see it for another minute—or longer if the polling interval is wide. For a fulfillment center managing dozens of riders, polling also multiplies server load and can trigger rate limits.

Webhooks solve this by pushing events as they happen. When an order moves from accepted to picked_up, the logistics API sends an HTTP POST to your endpoint immediately. Your dashboard updates in near real time, and you only process data when something actually changes. This is the difference between a dashboard that feels live and one that feels like a clock that ticks slowly.

How Webhook Events Work in a Logistics API

In a webhook-first logistics API, events are structured around order status changes. The most common event type is order.status_changed, which carries the order ID, the new status, and a timestamp. The typical status taxonomy includes: accepted, assigned, picked_up, in_transit, delivered, failed, and cancelled. Each event tells you exactly where the order is in the fulfillment flow.

For example, when a fulfillment center accepts an order, you get an accepted event. When the FC assigns a rider, you get assigned. When the rider picks up the package, picked_up. This granularity lets you build a dashboard that shows the exact stage of every order, and you can trigger customer notifications automatically without polling.

Event Payload and Idempotency

Each webhook payload should include a unique event ID and the order reference. To avoid duplicate processing, your endpoint must be idempotent—meaning that if the same event is delivered twice (which can happen during retries), your system should recognize it and not double-process. The simplest way is to store the event ID and ignore repeats. In Relay's API, the external_ref field lets you map orders to your own reference, making idempotency checks straightforward.

Securing Webhooks with HMAC Signatures

Webhooks are public URLs, so anyone could send fake events if you don't verify them. The standard defense is HMAC-SHA256 signing. The logistics API signs each payload with a secret key, and your endpoint verifies the signature before processing. Relay uses a verify-relay-signature-v2 header that combines a timestamp and the raw request body, hashed with HMAC-SHA256.

Here is a practical verification flow (in pseudocode, because the actual implementation depends on your stack):

1. Extract the verify-relay-signature-v2 header from the request.
2. Split the header into timestamp and signature parts.
3. Reject the request if the timestamp is older than, say, 5 minutes—this prevents replay attacks.
4. Concatenate the timestamp and the raw request body (the exact format is defined in the API docs).
5. Compute HMAC-SHA256 using your shared secret.
6. Compare the computed signature with the one in the header using a constant-time comparison.

If they don't match, return a 401 and don't process the event. This ensures that only legitimate events from the logistics API update your dashboard.

Handling Retries and Failures

Webhooks can fail—your server might be down, or a network error might occur. A robust logistics API will retry failed deliveries with exponential backoff, but you also need a dead-letter queue (DLQ) for events that keep failing after multiple attempts. This is a separate storage area where you can inspect and manually replay events later.

For your endpoint, always respond quickly with a 2xx status (like 200 or 204) once you've successfully processed the event. If you return a 4xx or 5xx, the API will retry. To avoid processing the same event twice, use the event ID for idempotency. If you need to perform a slow operation (like updating a database), consider queuing the event internally and responding immediately, then processing asynchronously.

Building a Webhook-First Integration with Relay

Relay's logistics API is designed for webhooks from the start. You create orders via the /merchant-api/v1/orders endpoint and receive real-time status updates via webhook notifications. The order statuses follow the standard taxonomy, and each event includes the order number and a delivery PIN for customer tracking. This means your dashboard can show the exact stage of every order, and you can trigger customer notifications automatically.

For developers, the integration is straightforward: set up an endpoint to receive webhook notifications, verify the signature, and update your systems. The API documentation covers the exact payload format and signature algorithm. For merchants and fulfillment centers, this translates to a dashboard that updates instantly when a rider marks an order as delivered, without manual refreshes or polling scripts.

Why Your Customers Care About Webhooks

When your dashboard updates in real time, your customers feel it. They can track their order from accepted to delivered without refreshing the page. The track order page uses the order number and delivery PIN, so the customer sees the same status you see. This shared visibility reduces support calls—customers don't need to ask "where is my order?" because they can see it themselves.

For fulfillment centers, webhooks also improve coordination. When a rider marks a delivery as complete, the FC dashboard updates immediately, and the merchant gets notified. This creates a single status trail that all parties can rely on, from order creation to proof of delivery.

Bottom Line

Switching from polling to a logistics API with webhooks is not just a technical upgrade—it's a business upgrade. You get real-time updates, lower server load, and a better customer experience. With HMAC-signed webhooks and idempotent retries, you can build a reliable integration that never misses an event. If you're evaluating logistics APIs, make webhooks a non-negotiable requirement.