Testing webhooks
Receive sandbox webhooks on your laptop with a tunnel, trigger every event on demand, and check your handler before go-live.
- Product
- APIShipping Engine API
- Section
- Webhooks
- Reading time
- 5 min read
In this guide you expose your local handler through an HTTPS tunnel, register it in the sandbox, and trigger events with simulated shipment statuses.
Before you start: you need sandbox API credentials and an access token (see the
Quickstart), a webhook handler running locally (see Webhooks),
and a sandbox shipment created with POST /b2b/orders that has an airway bill.
Expose your handler with a tunnel
Shipping Engine only calls public HTTPS URLs with a valid certificate, so
localhostwon't work. A tunnel gives your local port a public HTTPS address. Start your handler (here on port 3000), then run one of these:ngrok http 3000InboundOutput Forwarding https://4f2a-203-0-113-7.ngrok-free.app -> http://localhost:3000Your webhook URL is the tunnel address plus your route, for example
https://4f2a-203-0-113-7.ngrok-free.app/webhooks/shipping-engine.Interstitial pages
Some tunnel plans show a browser warning page or require a login for unknown clients. Shipping Engine can't click through it, so the challenge fails. Use a plan or setting that forwards requests straight to your app.
Register the tunnel URL in the sandbox
Register against the sandbox API with a test secret. Sandbox and production have separate endpoints, so this doesn't touch your production webhook.
curl -s -X POST "$FASTRAC_API/b2b/webhook/setWebhook" \ -H "Authorization: Bearer $FASTRAC_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "Local testing", "url": "https://4f2a-203-0-113-7.ngrok-free.app/webhooks/shipping-engine", "secret": "'"$FASTRAC_WEBHOOK_SECRET"'", "keyId": "local-test", "eventTypes": ["shipment.*"] }'Check that the response has
"challenge": { "success": true }and"verificationStatus": "verified". Your handler log should show one unsignedPOSTwith achallengebody.Each tunnel restart may change the URL
Free tunnels often get a new address every time they start. Register the new URL again each time; until you do, the old URL receives the events and they fail.
Trigger events
In the sandbox,
POST /b2b/shipments/{shipmentCode}/simulate-statuspretends the courier reported a status, and Shipping Engine sends the matching webhook. It needs theCANCEL_ORDERpermission and works only in the sandbox; production returns403.curl -s -X POST "$FASTRAC_API/b2b/shipments/SHP-261120-7RT2WX/simulate-status" \ -H "Authorization: Bearer $FASTRAC_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "status": "TRANSIT" }'InboundResponse { "statusCode": 200, "message": "Shipment status simulated successfully." }statusyou sendEvent(s) you receive What changes on the sandbox shipment DRIVER_ASSIGNEDshipment.pending_pickupwith sample driver fieldsDriver details only TRANSITshipment.in_transitStatus becomes IN_TRANSITDELIVEREDshipment.deliveredStatus becomes DELIVERED(final)CANCELLEDNone. To test shipment.cancelled, cancel the shipment with the cancel endpoint instead (see below)Status becomes CANCELLED, sandbox balance refundedRTSshipment.rts_billedif the courier charges a return fee. Use theRTS_BILLEDsimulation to test that event on its ownStatus becomes RTS_DELIVERED(final)AIRWAYBILL_UPDATEDshipment.airway_bill_updatedAirway bill replaced with a test value starting with SIM-PRICE_CHANGEDshipment.price_changedwith sample values (10000→15000,delta5000)Nothing: event only WEIGHT_CHANGEDshipment.measurement_changedwith sample valuesNothing: event only RTS_BILLEDshipment.rts_billedwith a samplerts_feeof15000Nothing: event only You also receive
shipment.dispatchedeach time you create a sandbox order, andshipment.cancelledwhen you cancel a sandbox shipment withPOST /b2b/shipments/cancel/{shipmentCode}.Final statuses are final in the sandbox too
After
DELIVERED,RTSorCANCELLED, later simulations on that shipment don't change it and may send nothing. Use a fresh sandbox shipment for each end-to-end run. Simulations need a shipment that has an airway bill; an unknown shipment code returns400 Shipment SHP-… not found.A realistic sequence for one shipment: create the order (
shipment.dispatched) →DRIVER_ASSIGNED→TRANSIT→DELIVERED. Use a second shipment forTRANSIT→RTS, and cancel a third withPOST /b2b/shipments/cancel/{shipmentCode}to receiveshipment.cancelled.Check your handler
For each event, confirm in your logs and database that:
- The signature check passed (and a request with a changed body or wrong secret fails with
401). - The
x-webhook-idwas stored, and sending the same event twice is processed once. - Your handler answered
200in well under a second. - The shipment's status in your system matches
data.status, and an olderdata.timestampdoesn't overwrite a newer one. - Events you don't handle still get
200.
To test retries, make your handler return
503once and watch the next attempt arrive about a second later withx-webhook-attempt: 2and the samex-webhook-id.- The signature check passed (and a request with a changed body or wrong secret fails with
Before you go live
- Production endpoint on a stable HTTPS URL with a certificate from a public authority. No tunnel.
- A new production secret (at least 32 characters), different from the sandbox one, stored in a secret manager.
- Endpoint registered with the production API, and
challenge.successistrue. - Signature verification on the raw body, constant-time compare, 300-second timestamp check, secret selected by
keyId. - Unsigned challenge requests are echoed; unsigned anything-else is never processed.
-
2xxreturned right after the event is stored; processing happens in the background. - Duplicates dropped by
x-webhook-id; status updates are idempotent and ignore older timestamps. - Unknown event types answered with
200. - A scheduled reconciliation job using
GET /b2b/shipments. See Delivery and retries. - Monitoring on signature failures, non-
2xxresponses, andfailureCount/backoffUntilfromGET /b2b/webhook/info.
See Go live for the rest of the production checklist.
Was this page helpful?