Skip to Content
FastracDocs

Delivery and retries

How Shipping Engine delivers events, when it retries, and how to design a handler that never misses a shipment update.

Product
APIShipping Engine API
Section
Webhooks
Reading time
5 min read

Shipping Engine delivers each event at least once, in no guaranteed order, and retries for about two minutes. Design your handler for duplicates, out-of-order events and the occasional missed event.

What counts as delivered

Your endpoint…Result
Returns any 2xx within the timeoutDelivered. The response body is ignored.
Returns 5xx, 408, 409 or 429Failed, retried.
Times out, refuses the connection, or fails TLSFailed, retried.
Returns 3xxFailed, not retried. Redirects are not followed.
Returns any other 4xx (400, 401, 403, 404, 410, …)Failed, not retried.

Timeouts

LimitValue
Connect3 seconds
Whole request, including your responsetimeoutMs of your endpoint: 10 seconds by default, configurable from 1 to 60 seconds
Response body readFirst 64 KB. The rest is ignored.

If your endpoint finishes the work but answers after the timeout, the attempt still counts as failed and the event is sent again.

Retry schedule

A failed attempt is retried with exponential backoff. The wait doubles each time:

AttemptSent after the previous attempt failed
1Immediately when the event happens
21 second
32 seconds
44 seconds
58 seconds
616 seconds
732 seconds
864 seconds

With the default maxAttempts of 8, Shipping Engine gives up about 2 minutes after the first attempt. You can raise maxAttempts up to 50 when you register the endpoint; the wait keeps doubling, but no event is retried once it is more than 24 hours old.

Each attempt has a new x-webhook-timestamp and signature, the same x-webhook-id, and an x-webhook-attempt header with the attempt number (1, 2, 3…).

After the last attempt, the event is gone

Shipping Engine does not replay events that failed every attempt, and it does not queue events for an endpoint that is disabled, unverified or paused. Use reconciliation to catch up.

Endpoint pause

If your endpoint keeps failing, Shipping Engine stops sending to it for a while, so a broken endpoint doesn't receive a flood of retries.

  • After about 15 consecutive failed attempts across all events (for example, two events that both fail all 8 attempts), deliveries to your endpoint pause for 30 minutes.
  • New events that happen during the pause are dropped. They are not sent later.
  • Retries that were already scheduled wait until the pause ends.
  • GET /b2b/webhook/info shows the pause in backoffUntil and the streak in failureCount.
  • The first successful delivery resets failureCount to 0.

Ordering

Events can arrive out of order. A retry of an older event can arrive after a newer one, and two events can be sent at almost the same time. Don't assume the last request you received is the current status.

To keep your data correct:

  • Compare data.timestamp (the time of the status change, YYYY-MM-DD HH:mm:ss in UTC) with the one you stored, and ignore older updates.
  • Respect the status rules: DELIVERED and RTS_DELIVERED are final, and once a shipment is in a return status (RTS_*) it never goes back to IN_TRANSIT or PENDING_PICKUP. See Shipment statuses.
  • When in doubt, fetch the current state with GET /b2b/shipments/{shipmentCode}/details.

Duplicates

You can receive the same event more than once, for example when your 2xx was lost on the network or arrived after the timeout.

  • Deduplicate on x-webhook-id. It is the same on every retry of one event. Store the IDs you have processed (a few days is enough) and skip repeats, but still answer 2xx.
  • Make updates idempotent. The same status can also arrive as two different events (with different x-webhook-id values), for example shipment.in_transit each time the parcel reaches a new hub. Setting "status = IN_TRANSIT" twice should be harmless.

Design your handler

  1. Respond first, work later

    Verify the signature, save the raw event (or put it on a queue), and return 200 right away. Do the slow work, such as database updates, emails and calls to other services, in a background job. This keeps you well inside the timeout and avoids duplicate deliveries.

    In the requestFast: well inside the timeout
    POST arrivesRead the raw body
    Verify signatureReject if invalid
    Store the eventUnique on x‑webhook‑id
    Return 200 OKRight away
    queue
    In a background job
    Apply the statusOnly if newer than what you have
    Notify your customerEmail, push, update your UI
  2. Return the right status

    SituationReturn
    Event stored (or already seen)200
    Signature invalid401: not retried
    Your database or queue is down503: retried
    Event type you don't handle200: otherwise it counts as a failure
  3. Reconcile regularly

    Webhooks are a fast path, not a guarantee. Run a scheduled job, for example every 15–60 minutes, that compares your open shipments with Shipping Engine:

    1. Call GET /b2b/shipments with startDate and endDate covering your recent orders (and, if you like, a status filter), following nextCursor until it is null.
    2. For every shipment whose status differs from yours, fetch GET /b2b/shipments/{shipmentCode}/details and apply the change.
    3. Also check your balance logs for adjustments and return fees you didn't receive an event for.

    This catches anything missed while your endpoint was down, paused, disabled or misconfigured.

See Track shipments for the list and detail endpoints, and the API reference for every parameter.

Common mistakes

Doing the work before answering

Sending emails or calling other APIs before returning 200 makes you slow under load. Slow responses time out, are retried, and can pause your endpoint.

Returning 4xx for events you don't need

Answer 200 and ignore them. A 400 for an unknown event type is recorded as a failed delivery, and repeated failures pause your endpoint.

Relying on webhooks alone

If your endpoint is down for longer than the retry window, those events are lost. Without reconciliation, those shipments stay stuck in your system.

Was this page helpful?

On this page