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 timeout | Delivered. The response body is ignored. |
Returns 5xx, 408, 409 or 429 | Failed, retried. |
| Times out, refuses the connection, or fails TLS | Failed, retried. |
Returns 3xx | Failed, not retried. Redirects are not followed. |
Returns any other 4xx (400, 401, 403, 404, 410, …) | Failed, not retried. |
Timeouts
| Limit | Value |
|---|---|
| Connect | 3 seconds |
| Whole request, including your response | timeoutMs of your endpoint: 10 seconds by default, configurable from 1 to 60 seconds |
| Response body read | First 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:
| Attempt | Sent after the previous attempt failed |
|---|---|
| 1 | Immediately when the event happens |
| 2 | 1 second |
| 3 | 2 seconds |
| 4 | 4 seconds |
| 5 | 8 seconds |
| 6 | 16 seconds |
| 7 | 32 seconds |
| 8 | 64 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/infoshows the pause inbackoffUntiland the streak infailureCount.- The first successful delivery resets
failureCountto0.
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:ssin UTC) with the one you stored, and ignore older updates. - Respect the status rules:
DELIVEREDandRTS_DELIVEREDare final, and once a shipment is in a return status (RTS_*) it never goes back toIN_TRANSITorPENDING_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 answer2xx. - Make updates idempotent. The same status can also arrive as two different events (with
different
x-webhook-idvalues), for exampleshipment.in_transiteach time the parcel reaches a new hub. Setting "status = IN_TRANSIT" twice should be harmless.
Design your handler
Respond first, work later
Verify the signature, save the raw event (or put it on a queue), and return
200right 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 timeoutPOST arrivesRead the raw bodyVerify signatureReject if invalidStore the eventUnique on x‑webhook‑idReturn 200 OKRight awayqueueIn a background jobApply the statusOnly if newer than what you haveNotify your customerEmail, push, update your UIReturn the right status
Situation Return Event stored (or already seen) 200Signature invalid 401: not retriedYour database or queue is down 503: retriedEvent type you don't handle 200: otherwise it counts as a failureReconcile 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:
- Call
GET /b2b/shipmentswithstartDateandendDatecovering your recent orders (and, if you like, astatusfilter), followingnextCursoruntil it isnull. - For every shipment whose
statusdiffers from yours, fetchGET /b2b/shipments/{shipmentCode}/detailsand apply the change. - 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.
- Call
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?