Webhook Shipment Tracking: How Tracking Webhooks Work vs Polling (Payloads, Retries & Setup)

Shipment tracking webhooks send an HTTP request to your application when a tracking service has an update to report. Polling works in the opposite direction: your application repeatedly requests the latest tracking information. For developers connecting shipment data to an order management system, store, or customer notification service, webhooks are generally the better primary update mechanism when supported; targeted polling can help recover missed updates and reconcile records.

Neither method makes a carrier scan a parcel sooner. Both depend on when the tracking source receives and exposes new information. The practical difference is how your application learns about that information, how much request traffic it generates, and what happens when delivery fails.

Tracking webhooks vs polling: the operational difference

These are integration patterns, not competing tracking databases. A carrier or tracking platform may offer either pattern or both, with different access conditions. Compare the behavior of the specific API you plan to use rather than assuming that all webhook services share the same guarantees.

Choose webhooks first when timely updates matter and your team can operate a reliable receiver. Choose polling first when inbound endpoints are impractical, shipment volume is modest, or the source does not provide suitable webhooks. Use a hybrid design when missed updates would disrupt customer communications or operations and the API supports reconciliation.

Do not assume webhooks are cheaper. Subscription charges, tracking registration, API calls, event delivery, and infrastructure can be billed differently. Compare the actual commercial terms and expected workload rather than treating fewer requests as proof of a lower bill.

What happens between a carrier scan and your application?

1. Identify the shipment. Associate the tracking number, carrier information where required, and an internal shipment reference. Some services require registration before monitoring begins.
2. Configure event delivery. Provide an HTTPS callback URL and select any supported event subscriptions.
3. The source receives tracking information. A carrier scan or status change becomes available to the tracking service.
4. The service sends a webhook. The request may contain a full tracking snapshot, a single checkpoint, or only a reference requiring an API lookup.
5. Your receiver validates and stores it. Authenticate the request, check its structure, and durably record or enqueue the event.
6. A worker updates business systems. Normalize statuses, update shipment records, and trigger only the actions that are still appropriate.

A webhook delivery is not the same as a physical delivery. It is a message about shipment information. Likewise, a successful webhook response does not prove that an email was sent or that an order record was updated; those are downstream processing outcomes that need their own monitoring.

Reading a tracking webhook payload

The following JSON is an illustrative integration design, not a 17TRACK payload or a universal schema. Real field names, status codes, timestamp formats, and event identifiers must come from the selected provider's documentation.

{
  "event_id": "evt_example_001",
  "event_type": "shipment.updated",
  "created_at": "2025-04-08T10:16:00Z",
  "shipment": {
    "reference": "shipment_example_123",
    "tracking_number": "EXAMPLE123456",
    "carrier_code": "example_carrier",
    "status": "in_transit",
    "checkpoint": {
      "occurred_at": "2025-04-08T10:10:00Z",
      "description": "Departed processing facility"
    }
  }
}

Separate three clocks in your data model: when the shipment event occurred, when the provider generated the message, and when your application received it. A delayed checkpoint can arrive after a newer one. A timestamp without an offset also needs an explicit interpretation; do not silently treat every carrier-local timestamp as UTC.

Keep your internal shipment reference alongside the provider's identifiers. A tracking number alone may not be sufficient as a permanent global identifier, especially across different carrier contexts. For split orders, maintain shipment-level records rather than allowing one parcel's delivered status to mark the entire order complete.

Preserve the original status and description alongside your normalized business status. Your application may map several carrier messages to “in transit,” but support staff can still need the original checkpoint to understand a delay. Treat estimated delivery dates as estimates and distinguish a missing field from an explicit instruction to clear an existing value.

Retries, acknowledgments, and duplicate events

Webhook delivery can fail because of timeouts, network interruptions, authentication errors, or an unavailable receiver. A provider may retry, but there is no universal retry schedule, retention window, or maximum attempt count. Confirm which responses trigger another attempt, how redirects are handled, and whether manual redelivery is available.

Acknowledge after durable acceptance

Keep the request path short: validate the request, persist the accepted work, and return the success response required by the provider. Send emails and perform slower business operations asynchronously. The HTTP specification defines 202 Accepted as acceptance for processing rather than completed processing, but your provider may require a different success response. Follow its webhook contract.

Returning success before storing anything risks losing the update if your process crashes. Waiting for every downstream action risks a timeout and another delivery attempt. A durable inbox or queue provides a boundary between receipt and processing.

Make processing idempotent

Idempotency means that processing the same event again does not repeat its business effects. A sender can retry after your server accepted an event but its acknowledgment was lost. Duplicate delivery should therefore be a routine test case.

• Use a documented event identifier as a deduplication key when one is available, scoped to the correct provider or account.
• If no identifier exists, design a composite key from stable event fields and test its collision risks.
• Enforce uniqueness atomically in storage; a separate “check, then insert” sequence can race under concurrent delivery.
• Protect downstream actions too. A duplicate event must not send another delivery notification or repeat a financial action.
• Set retention according to the provider's replay behavior and your recovery requirements, rather than deleting deduplication records immediately.

Do not assume chronological arrival

Do not overwrite the current shipment state simply because a request arrived last. Compare event meaning, timestamps, and any documented sequence information. Preserve late checkpoints in history without automatically moving the displayed status backward. At the same time, allow documented corrections: a rigid rule that delivered shipments can never change can hide legitimate exceptions or corrected information.

A practical setup checklist

1. Confirm the provider contract

Before implementation, confirm registration requirements, supported events, payload shape, authentication, response expectations, timeouts, retry behavior, and API limits. Check whether a notification represents a snapshot or an incremental change, whether deliveries can contain multiple records, and whether subscribing sends an initial state.

For a 17TRACK integration, begin with the official Tracking API page and API documentation. Use the provider-specific documentation to establish request fields and callback requirements; the generic payload above is not a substitute. Confirm access conditions and operational limits for the integration you intend to deploy.

2. Secure the receiving endpoint

Use HTTPS and the authentication mechanism the provider documents. If it uses an HMAC signature, validate exactly the signed input it specifies. Where raw request bytes are signed, parsing and reserializing JSON before verification can change those bytes and invalidate the signature. Use constant-time comparison for secret-derived signature values.

If signed timestamps or delivery identifiers are available, apply the documented replay controls. A valid signature authenticates a message but does not, by itself, establish that it is fresh. Keep secrets out of URLs and application logs, support secret rotation, and restrict request sizes. IP allowlisting can be an additional control where maintained address ranges exist, not a replacement for message authentication.

3. Separate receipt from business processing

Store enough information to trace and safely replay an accepted event. Queue workers should normalize the update, apply state-transition rules, and record action outcomes. Put repeatedly failing work into a reviewable dead-letter workflow rather than retrying forever. Limit access and retention because tracking payloads can contain customer-related information.

4. Test failure paths before launch

• Send the same event twice, including concurrent deliveries.
• Deliver an older checkpoint after a newer one.
• Simulate a queue outage and a worker crash after receipt.
• Test invalid authentication, malformed JSON, and oversized requests.
• Test unknown shipments, missing optional fields, and added fields.
• Verify that one delivered parcel does not complete a split order.
• Replay an event after recovery and confirm notifications remain deduplicated.

Be tolerant of additive fields where safe, but do not silently reinterpret unknown status values. Preserve the raw value and route unrecognized cases through a defined fallback or review process.

Where polling still earns its place

Polling is useful for initial synchronization, recovery after an outage, and checking shipments whose expected updates have not arrived. However, silence alone is not proof of webhook failure: a parcel may genuinely have no new scans. Reconcile against the API's current state or history instead of assuming every quiet shipment needs an alert.

For scale planning, a simplified polling model is requests per hour ≈ active shipments × polls per shipment per hour, assuming one shipment per request. Batch endpoints change that calculation. As an illustration, 1,000 shipments checked four times per hour generate 4,000 requests per hour before retries; this is arithmetic, not a provider quota or pricing estimate.

Schedule checks according to shipment activity and business risk, respect rate limits, and add jitter so jobs do not all start together. For retryable failures, use bounded backoff and honor applicable server guidance. Do not repeatedly retry permanent credential or validation errors without correcting them.

A practical hybrid system uses webhooks for routine updates and targeted API reads for suspected gaps. Monitor receipt failures, queue age, processing failures, duplicate rates, and reconciliation mismatches separately. Where timestamps are trustworthy, distinguish source-data delay from webhook-delivery delay and internal processing delay.

FAQ

Are tracking webhooks real-time?

They can reduce the delay caused by waiting for the next polling cycle. They do not guarantee immediate carrier scans or instant source updates. End-to-end freshness includes carrier reporting, provider processing, request delivery, and your own application.

Can I stop polling completely after enabling webhooks?

Possibly, if the provider's recovery features and your business requirements make that acceptable. For operationally important shipment records, retain a reconciliation method. It can be targeted rather than continuous polling of every shipment.

What happens if my webhook endpoint is offline?

Recovery depends on the sender's documented retry policy. Do not assume retries continue indefinitely. After restoring the endpoint, inspect failed deliveries, use supported redelivery tools, and reconcile affected shipments through the API where available.

Should every webhook trigger a customer notification?

No. An event may be a duplicate, a historical checkpoint, or an update that does not change the customer-facing status. Trigger notifications from deduplicated business transitions, with rules for exceptions and corrections.

Does a successful HTTP response mean the shipment update is complete?

Not necessarily. In an asynchronous design, it means the receiver accepted the event under the agreed contract. Track processing completion and downstream notification outcomes separately so an accepted request cannot conceal a failed workflow.

Sources

• RFC 9110: HTTP Semantics — HTTP response semantics, including acceptance for processing and Retry-After.
• RFC 2104: HMAC—Keyed-Hashing for Message Authentication — the HMAC construction referenced in signature verification guidance.
• GitHub Docs: Best practices for using webhooks — general engineering guidance on HTTPS, secrets, asynchronous handling, and delivery identification; its service-specific rules do not establish shipment-provider behavior.
• 17TRACK Tracking API — official entry point for evaluating a 17TRACK tracking integration.
• 17TRACK API documentation — provider-specific reference for implementation requirements.