Tracking webhook: Explanation for developers and online retailers
A tracking webhook is an automated HTTP push message that transmits the shipment status to another system in real time as soon as the status changes. Instead of constantly querying an interface, the parcel service or shipping platform sends the new status directly to a URL provided by the recipient. This saves server load, significantly reduces latency compared to polling, and forms the technical basis for tracking dashboards, customer notifications, and automated customs processes. The following sections explain the underlying technology, the necessary security measures, and provide a concrete code example.
In short:
- Tracking webhooks report status changes in real time and reduce server load through push-based notifications compared to polling.
- Signature verification is performed using the unmodified request body with HMAC-SHA256 to ensure authenticity and integrity.
- Received webhook events are immediately placed in a queue to avoid timeouts and processing delays.
- The system should cache event IDs and process them idempotently to reliably prevent duplicate deliveries.
- Paket International simplifies the integration of webhooks through a central interface that bundles shipment events in a dashboard.
Table of Contents
- What is a tracking webhook? Definition and typical tracking events
- How is the message of a tracking webhook structured?
- How do you secure a webhook receiver?
- How do you process webhook events without risking timeouts?
- What does an example code for receiving a webhook look like?
- What specific purpose do tracking webhooks serve in shipping?
- How do you detect webhook failures before customers do?
- Checklist: Bringing a webhook endpoint live in ten steps
- How a shipping platform practically uses webhooks
- Sources
- FAQ
What is a tracking webhook? Definition and typical tracking events
A webhook works in reverse to a traditional API. With a normal API, your system actively queries for updates. A webhook reverses this: the sender notifies you as soon as something happens, which is why this pattern is often called a reverse API. Instead of checking with the parcel service every minute to see if there's anything new, your system registers a receiving address once, and the sender only provides updates when needed.
In the context of shipping, virtually every status change triggers a separate event. Typical tracking events include:
- Shipping label has been created
- The shipment was picked up by the parcel service.
- The shipment was scanned at a sorting center.
- Shipment is out for delivery
- The shipment was successfully delivered.
The advantage is obvious: real-time updates without repeated queries, reduced processing load on both sides, and a natural basis for automation. The disadvantage only becomes apparent during operation: your system must be accessible at all times, absorb outages, and handle duplicate or delayed messages. This is precisely what the following sections address.
How is the message of a tracking webhook structured?
Technically, a tracking webhook is simply an HTTP POST request to a URL you define. The payload that arrives almost always follows a four-part pattern: a unique event ID, an event type, a timestamp, and a data object containing the actual shipment information. This envelope format is so widespread in practice that it has become synonymous with... De facto standard for webhook payloads established hat.
In addition to the message body, the HTTP headers contain important additional information. Content‑Type: application/json This includes a signature header (often) X‑Signature or X‑Hub‑Signature‑256) and a Delivery ID, which allows individual delivery attempts to be distinguished.
One point is often overlooked in practice: The signature must be above the raw, unaltered body The hash must be calculated before any JSON library parses it. Even a change in formatting, such as different spaces, leads to a different hash and thus to a message being incorrectly rejected.
How do you secure a webhook receiver?
A recipient is only ready for production when it reliably answers three questions: Does the message really come from the stated sender? Has it already been processed? What happens if processing fails? Anyone who ignores these three questions will sooner or later receive duplicate order confirmations or missed customs declarations.
Signature verification using HMAC-SHA256 on the raw body is the first step. The shared secret between sender and receiver generates a hash, which the receiver recalculates and compares. The type of comparison is crucial: A normal string comparison with === It is measurably insecure because it immediately terminates at every incorrect character, thus revealing a timing difference that attackers can exploit. In Node.js, this is handled by... crypto.timingSafeEqual This task is constant over time; in Python, the corresponding compare_digest-Function.
- Always check the signature using the unaltered raw text, never the already parsed object.
- Check the timestamp in the payload against a time window of approximately five minutes to prevent replay attacks with old but validly signed messages.
- Cache previously processed event IDs to prevent duplicate processing of repeated deliveries.
- To technically enforce idempotence, for example via an atomic database insert with a UNIQUE constraint or a
SET NXin Redis - Events that have ultimately failed after several attempts should be moved to a dead-letter queue instead of being silently discarded.
This combination of signed timestamps and ID caching to protect against replay attacks is also used in common Security guides for webhooks empfohlen.
Important for managing expectations: Almost all webhook senders operate on the "at-least-once" principle, meaning they deliver at least once. In practice, this means that duplicate deliveries are the norm, not an error. A system that doesn't process idempotently will sooner or later produce duplicate shipment notifications or incorrect customs statuses.
Pro tip: Do not delete cached event IDs immediately after processing, but only after the sender's retry window has expired. Many providers repeat failed deliveries over several hours or days, and an ID deleted too early opens precisely the gap that the idempotence check is supposed to close.
How do you process webhook events without risking timeouts?
The biggest operational risk with webhooks isn't security, but response time. Parcel services and shipping platforms impose strict time limits: some providers expect a 2xx response within just a few seconds, while others allow up to 30 seconds, as GitHub describes in its own recommendations. If this window is exceeded, the sender considers the delivery a failure and resends it, flooding your database with even more duplicates.
The solution is a strict separation between receiving and processing:
- Instantly verify raw data and signatures without complex business logic.
- Write the event to a queue, for example using BullMQ, Amazon SQS or pg-boss.
- Immediately with
200 OKrespond before the actual processing begins. - A separate background worker retrieves the job from the queue and executes the actual logic.
- The job ID in the queue corresponds to the event ID, so the queue itself is also deduplicated.
Anyone who handles webhook processing in a blocking manner within the request itself will sooner or later run into a conflict with the sender's timeout. Events should be immediately queued; the actual processing runs asynchronously in the background.
The idempotency TTL, i.e., the time an event ID remains in the cache, should be based on the sender's actual retry window, not an arbitrary number. For capacity planning, it's worth considering the queue depth: if it grows continuously, the worker processes events more slowly than they arrive, and backpressure mechanisms should be implemented before the memory overflows. An alert for the dead-letter queue should be implemented from the outset, as a growing DLQ is usually the earliest warning sign of a deeper problem.
What does an example code for receiving a webhook look like?
A clean handler always follows the same order: first check, then store, then process. The following flow is based on common Node.js patterns and can be transferred to any language that supports HMAC and atomic database operations.
- Read the request body as an unmodified raw format, without parsing it beforehand.
- Extract the signature sent from the header.
- Using the shared secret, calculate the expected HMAC-SHA256 signature from the raw text.
- Compare both signatures using a time-constant function, never using a simple equality operator.
- Only parse the body as JSON after successful verification.
- Write the event ID atomically to the database, for example using a UNIQUE constraint that automatically rejects duplicates.
- Place the event in the processing queue.
- Immediately with
200 OKanswer.
The reason for the order in step 5 is simple: anyone who parses JSON before verifying the signature is processing potentially manipulated data, even if the processing itself appears harmless. Validate first, then interpret.
When errors occur, correct HTTP semantics are crucial. 4xx-Status signals to the sender “this message is fundamentally flawed, do not repeat it”, for example in the case of an incorrect signature. 5xx-Status means “something is broken on my end, please try again later”, for example in the case of a database failure.
Pro tip: Log each rejected signature with a timestamp and source IP address. A sudden spike in failed signature checks is often the first sign of a misconfigured secret after a rotation, not an attack.
What specific purpose do tracking webhooks serve in shipping?
In the day-to-day operations of an online shop, tracking webhooks take over tasks that previously required manual tracking. As soon as a parcel service reports a new scan, the webhook automatically updates the public tracking page, triggers a notification to customers, or initiates an internal fulfillment step, such as approving an invoice after delivery.
- Tracking pages display the current status without delay caused by manual checking.
- Customer notifications via email or SMS are sent automatically for every relevant status change.
- Internal systems such as shop, ERP or CRM receive the new status via a streamlined payload, without anyone having to manually enter data.
- WISMO inquiries (“Where Is My Order”) are decreasing significantly because customers can check the status themselves.
- Customs-relevant status changes can be automatically forwarded to customs systems, without paper processes.
Important: The webhook itself often only provides key information such as the tracking number and current status. For more detailed information, some parcel services also refer to a separate tracking API, which is queried as needed. Those who manage their shop via WooCommerce or connects a comparable system, these events are usually fed directly into the existing order management system.
How do you detect webhook failures before customers do?
A webhook system without monitoring operates blindly. The most important key performance indicators (KPIs) are the Delivery Success Rate (DSR), i.e., the percentage of successfully processed deliveries, the Retry Rate, the Delivery Quality Depth (DLQ), and the processing latency between receipt and completion.
- A delivery success rate below the usual level indicates a problem with signature verification or accessibility.
- A growing DLQ depth indicates that events ultimately fail, not just are delayed.
- An alert triggered after approximately five consecutive failures at an endpoint prevents a failure from going unnoticed for hours.
- Increasing processing latency is often the earliest sign of an overloaded queue.
The stringency of the alert threshold depends on the event type: For payment-related events, an alert is warranted even after a single failed attempt, while for purely analytics-related events, a higher tolerance is sufficient. Before going live, test cases for repeated deliveries, incorrectly formatted payloads, and artificially slowed downdown processing should be included in every checklist.
Pro tip: Simulate a complete outage of your own endpoint for five minutes and observe how the sender's retry queue behaves. This will allow you to see before going live whether your DLQ and alerts are actually working.
Checklist: Bringing a webhook endpoint live in ten steps
- Define the relevant events that your system actually needs.
- Keep the payload as minimal as possible; do not subscribe to unnecessary fields.
- Force HTTPS and generate a secret for signature verification.
- Make the raw request body available without prior parsing.
- Check HMAC signature with time constant comparison.
- Write the event ID atomically to the database to prevent duplicates.
- Place the event in a processing queue.
- Within the time frame set by the sender with
200 OKanswer. - Set up a dead-letter queue and alerting for failed events.
- Document your own expectations regarding events, fields, and retry behavior.
| Step group | Objective | Typical tool |
|---|---|---|
| Safety | guarantee the authenticity of the message | HMAC-SHA256, HTTPS |
| application | Avoid timeouts | BullMQ, SQS, pg-boss |
| Operation | Detect failures early | Dead letter queue, alerting |
How a shipping platform practically uses webhooks
Anyone who develops their own tracking webhooks quickly realizes how much operational work goes into signature verification, queues, and customs status logic before the first status update reliably reaches the customer. Paket International takes over precisely this part of the shipping chain and automates status updates, customs triggers, and central shipment tracking, so online retailers don't have to build their own webhook receiver for each individual parcel service.
The platform connects parcel services such as DHL, UPS, FedEx, DPD and DB Schenker via a common interface and consolidates their shipment events in one central location. Tracking dashboardAPI and plugin integrations, for example for WooCommerce or similar shop systems, allow these events to be fed directly into existing processes, instead of connecting each provider individually. This not only reduces development effort but also lowers costs. Sea According to Paket International, shipping costs are significantly reduced because customs clearance and document creation are automated instead of being processed manually. Anyone who entrusts international shipping, including customs clearance, to a Shipping platform who wishes to hand over can find under the current shipping rates the right starting point for your own shipment volume.
FAQ
What is a webhook, explained simply?
A webhook is an automated message that one system sends to another as soon as a specific event occurs, such as a shipment status change. Unlike a traditional query, the recipient doesn't have to constantly check but is actively notified as soon as there is something new.
How do I program a webhook?
To receive the event, you set up an HTTPS endpoint that reads the raw request body, verifies the accompanying signature with a time-constant comparison, and only then processes the event as JSON. You then atomically write the event ID to a database, place the job in a queue, and respond immediately. 200 OK, so that the sender does not repeat the delivery.
What distinguishes a webhook from a classic API query?
With a traditional API, your system actively requests new data, often at fixed intervals, even if nothing has changed. A webhook reverses this: The sender only sends a request when an event has actually occurred, thus reducing server load and latency.
How can you protect yourself against duplicate webhook deliveries?
Duplicate deliveries are normal for most webhook senders, as many providers operate on the "deliver at least once" principle. An atomic database insert with a UNIQUE constraint on the event ID or a SET NX In Redis, this prevents an already processed event from being executed again.
Does Paket International offer its own webhook integration?
Paket International consolidates shipment events from multiple parcel services into a central tracking dashboard and makes this information available to shop systems via API and plugin integrations. Details on technical integration options and current terms and conditions can be found directly on the [website/platform name]. Platform page.