Skip to main content
HomeBlogGuidesTesting a Tracking API Integration in Development: Sandbox, Test Numbers, Mock Webhooks

Testing a Tracking API Integration in Development: Sandbox, Test Numbers, Mock Webhooks

17TRACK

To test a tracking API integration in development, use three complementary methods: a provider sandbox or documented test numbers for API behavior, local fixtures for repeatable shipment scenarios, and mock webhooks for your receiving endpoint. Then run a controlled live check to validate the parts that simulations cannot prove, including credentials, subscription configuration, and actual event delivery.

Testing a Tracking API Integration in Development Sandbox Test Numbers

This guide is for developers connecting shipment tracking to an ecommerce platform, order management system, ERP, or customer notification service. The goal is not simply to receive a successful API response. It is to prove that tracking updates produce the correct order state without duplicate messages, lost events, or accidental contact with real customers.

Separate provider behavior from application behavior

A tracking integration has at least two boundaries: requests your application sends to the provider, and updates your application receives or retrieves afterward. A successful request at the first boundary does not establish that the second boundary works.

Build the test plan around those boundaries rather than expecting one test tracking number to exercise the entire system.

Test methodWhat it can validateWhat it cannot establish alone
Provider sandboxSupported request formats, authentication, and simulated behavior described by the providerProduction carrier data availability or production delivery behavior
Documented test numbersThe specific scenarios assigned to those numbersOther statuses, carriers, or webhook sequences
Local fixtures and API mocksYour parser, mapping rules, persistence, and failure handlingWhether the real provider accepts requests or emits the same payload
Mock webhook requestsEndpoint handling, validation, deduplication, and downstream effectsProvider-side callback configuration or real delivery retries
Controlled live testReal connectivity and the observed shipment workflowEvery rare error, exception, or delivery sequence

Recommended approach: make local tests deterministic, use provider-supported testing where available, and reserve live shipments for confirming the connection between systems.

Confirm the provider contract before writing fixtures

Start with the official documentation for the API version you intend to use. Confirm the base URL, authentication method, registration requirements, response schema, webhook setup, and any documented testing facilities. Do not infer that a separate sandbox exists because the provider offers an API.

For a 17TRACK integration, use the 17TRACK Tracking API page and official API documentation as the starting points. Verify the applicable request and callback specifications there before building provider-specific examples. The examples below are deliberately application-owned fixtures, not representations of the 17TRACK API schema.

Resolve these questions before connecting development code to an external account:

  • Are development and production credentials separate, and what environment does each credential access?
  • Does a sandbox support callbacks, or only request-response testing?
  • Are test numbers documented, and what exact outcomes do they produce?
  • Can registrations or other test requests consume account quota or create persistent records?
  • What callback authentication, acknowledgement, timeout, and retry rules are documented?
  • Which identifiers connect a tracking registration, shipment, carrier, and callback event?

If testing behavior is not documented clearly, ask the provider to confirm it. Meanwhile, continue testing your own processing logic with mocks. An unconfirmed sandbox capability is a planning uncertainty, not evidence that the provider lacks that capability.

Build an isolated development environment

Use a separate database or isolated tenant, separate secrets, and synthetic orders. Route emails, SMS messages, and other notifications to test destinations or a notification sink. A shipment marked delivered in a fixture must not trigger a message to a real buyer.

Add an explicit environment marker to internal records and logs. Keep provider credentials on the server, outside source control, and redact secrets from request captures. If temporary public access is needed for callbacks, expose only the intended development route and retain its authentication controls.

Create a small set of known orders before sending events. Include two shipments attached to one order and, if your application supports it, the same tracking-number string under different carrier contexts. These cases reveal assumptions that a tracking number alone always identifies a unique business record.

Define the expected effect of each test in advance: the shipment state, order association, timeline entries, notification count, and audit record. This turns a demonstration into an assertion that can pass or fail.

Use test numbers only for their documented purpose

A tracking number has two distinct testing roles. It can be an input used to validate registration, and it can identify a shipment that produces tracking events. A number that passes format validation does not necessarily provide a useful event history.

When official test numbers are available

Record the provider's stated scenario alongside each number. A number documented for a delivered shipment should not be assumed to simulate an exception, return, or failed delivery attempt. Also check whether its result is fixed, changes over time, or requires a particular carrier selection.

Keep these numbers in a dedicated integration-test configuration. Do not scatter them through unit tests, where changing external behavior could make otherwise deterministic tests unreliable.

When official test numbers are not confirmed

Use synthetic identifiers inside your own application and mock the provider boundary. Never invent a plausible-looking number and assume it is reserved for testing: it could match a real shipment.

For live validation, use shipments you control and are authorized to access. Avoid copying tracking numbers from public screenshots or customer conversations. Treat shipment histories as potentially sensitive because they can contain locations, timestamps, and delivery information.

An older delivered shipment may help validate parsing, but it is a poor dependency for continuous integration. Historical data availability and the external response can change. Preserve a sanitized fixture for repeatable tests and keep the live check separate.

Create fixtures around meaningful shipment transitions

Build fixtures from the documented schema and, when available, sanitized real responses. Keep provider payload fixtures separate from your internal normalized event model. Test the adapter between them so that an internal mock does not hide a broken provider parser.

A useful starting set covers these scenarios:

  • No tracking events yet: retain the shipment without claiming movement or delivery.
  • In transit: update the timeline and preserve the correct order association.
  • Out for delivery: apply your notification policy without treating delivery as complete.
  • Delivered: record completion and emit the intended business action once.
  • Exception or attempted delivery: preserve the distinction from a completed delivery.
  • Return movement: avoid interpreting every later scan as progress toward the original recipient.
  • Unknown status: retain enough information for diagnosis without inventing a status mapping.

Use your own normalized names for these scenarios, then explicitly map the provider's documented values to them. Do not assume that different APIs use the same status labels or that a label has identical business meaning everywhere.

Also vary the shape of the data: an empty event list, missing optional fields, additional unknown fields, Unicode location names, timestamps with timezone offsets, and malformed required values. Your parser should tolerate compatible additions while rejecting data that cannot be processed safely.

Send mock webhooks through the real receiving path

A mock webhook should exercise the receiving route, authentication middleware, validation, storage, and worker processing—not merely call the final status-update function.

The following payload represents a synthetic internal event. The field names, event ID, and status are illustrative; they are not a provider callback contract.

{
  "event_id": "dev-event-001",
  "shipment_id": "dev-shipment-001",
  "tracking_number": "INTERNAL-TEST-001",
  "status": "in_transit",
  "occurred_at": "2025-01-15T10:00:00Z"
}

Save it as tracking-event.json and post it to a local test receiver:

curl --request POST \
  http://localhost:3000/dev/tracking-events \
  --header 'Content-Type: application/json' \
  --data-binary @tracking-event.json

This command validates local routing and handling only. It does not demonstrate provider authentication. Keep a development-only route inaccessible in production, or test the production receiver using the provider's documented authentication method and a separate test secret.

Test authentication without weakening production controls

If the provider specifies signed callbacks, implement that exact scheme rather than choosing an arbitrary signature header or algorithm. For schemes that sign request bytes, retain the original body for verification; parsing and reserializing JSON can change those bytes.

Test valid authentication, missing credentials, tampered bodies, and incorrect signatures where applicable. If the documented scheme includes timestamps or replay protection, test those rules too. HMAC is a standardized message-authentication construction, but its existence does not establish that a particular tracking provider uses it.

Test duplicates, ordering, and recovery

Shipment processing should remain correct when the same update arrives repeatedly or events arrive in an unexpected order. These are defensive test scenarios, not claims about a particular provider's delivery guarantee.

TestExpected application behavior
Send the same event twiceKeep one logical event and avoid duplicate customer notifications.
Send an older transit scan after deliveryPreserve useful history without automatically reversing the delivered state.
Send simultaneous updatesApply consistent state transitions despite concurrent workers.
Stop processing after durable receiptRecover and process the stored event without requiring a new callback.
Fail storage before receipt is durableDo not falsely acknowledge successful acceptance.
Send an unknown shipmentFollow a defined quarantine or rejection policy; never guess the order association.

Prefer a documented stable event identifier for deduplication when one is supplied. Otherwise, define a carefully scoped identity from relevant fields and test collisions. A tracking number by itself is not an event identity because one shipment can generate many legitimate updates.

Separate event history from the current shipment projection. Keeping historical scans does not require letting every late-arriving scan overwrite the displayed status. Nor is “use the newest timestamp” a complete rule: corrections, return flows, and different timestamp meanings require explicit handling.

For asynchronous processing, acknowledge only after the event reaches a durable handoff point, such as a committed inbox record or durable queue, according to your architecture. Follow the provider's documented acknowledgement requirements. HTTP defines status-code semantics, but a particular sender's retry schedule must come from its own contract.

Run a controlled live check and set release criteria

Once deterministic tests pass, register an authorized shipment through the real integration and confirm the complete path. Check that the provider accepted the intended record, the callback configuration points to the correct environment, and incoming data maps to the expected shipment.

Do not require every shipment status to appear during that live check. Real shipments are not controllable fixtures. Use the live run to validate connectivity and observed contract compatibility; use replayable fixtures to cover rare or destructive scenarios.

Before release, require the following outcomes:

  • Documented success and error responses are handled, including item-level failures if the API supports batch operations.
  • Timeouts do not trigger blind creation retries when the first request may already have succeeded.
  • Duplicate events cannot create duplicate business actions.
  • Invalid callbacks cannot change shipment state.
  • Worker failures leave recoverable events rather than silently losing them.
  • Development traffic cannot notify real customers or mutate production orders.
  • Logs connect requests, received events, processing results, and notification attempts without exposing secrets.

A release is ready when you can explain both the normal workflow and how the system recovers after an uncertain request, repeated callback, or interrupted worker. A single successful tracking lookup is not enough.

FAQ

Can I test a tracking integration without a sandbox?

Yes. Mock the outbound API boundary, replay documented callback fixtures, and test your normalization and business rules locally. Then use an authorized live shipment to confirm actual connectivity. This provides substantial coverage, but it does not reproduce undocumented provider behavior.

Why does my tracking request succeed but return no events?

Request acceptance and tracking-data availability are different outcomes. Check the provider's response details, registration requirements, carrier identification rules, and documented behavior for shipments without events. Do not manufacture movement or delivery information to fill an empty timeline.

Does a successful mock webhook prove that real webhooks will arrive?

No. It proves only the path exercised by the mock. Real delivery also depends on provider configuration, public reachability, TLS, authentication, and the actual callback contract. Validate those with a provider-supported test delivery or an authorized live workflow.

Should I return HTTP 200 before processing finishes?

Follow the provider's documented acknowledgement contract. In an asynchronous design, acknowledge after durable acceptance, then process in a worker. Returning success before durable acceptance can lose an event if the process fails immediately afterward.

How should I test customer notifications?

Send all development notifications to a controlled sink. Assert the destination, template, triggering transition, and number of sends. Replay the same event and simulate worker retries to verify that one shipment update does not generate repeated customer messages.

Sources

  • 17TRACK Tracking API — official starting point for the tracking API product.
  • 17TRACK API documentation — reference for the provider-specific integration contract; confirm applicable testing and callback requirements here.
  • RFC 9110: HTTP Semantics — HTTP response semantics and considerations for retrying requests.
  • RFC 2104: HMAC — the standardized message-authentication construction discussed in the callback security guidance.