Skip to Content
FastracDocs

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.

  1. Expose your handler with a tunnel

    Shipping Engine only calls public HTTPS URLs with a valid certificate, so localhost won'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 3000
    InboundOutput
    Forwarding  https://4f2a-203-0-113-7.ngrok-free.app -> http://localhost:3000

    Your 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.

  2. 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 unsigned POST with a challenge body.

    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.

  3. Trigger events

    In the sandbox, POST /b2b/shipments/{shipmentCode}/simulate-status pretends the courier reported a status, and Shipping Engine sends the matching webhook. It needs the CANCEL_ORDER permission and works only in the sandbox; production returns 403.

    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."
    }
    status you sendEvent(s) you receiveWhat changes on the sandbox shipment
    DRIVER_ASSIGNEDshipment.pending_pickup with sample driver fieldsDriver details only
    TRANSITshipment.in_transitStatus becomes IN_TRANSIT
    DELIVEREDshipment.deliveredStatus becomes DELIVERED (final)
    CANCELLEDNone. To test shipment.cancelled, cancel the shipment with the cancel endpoint instead (see below)Status becomes CANCELLED, sandbox balance refunded
    RTSshipment.rts_billed if the courier charges a return fee. Use the RTS_BILLED simulation 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_changed with sample values (10000 → 15000, delta 5000)Nothing: event only
    WEIGHT_CHANGEDshipment.measurement_changed with sample valuesNothing: event only
    RTS_BILLEDshipment.rts_billed with a sample rts_fee of 15000Nothing: event only

    You also receive shipment.dispatched each time you create a sandbox order, and shipment.cancelled when you cancel a sandbox shipment with POST /b2b/shipments/cancel/{shipmentCode}.

    Final statuses are final in the sandbox too

    After DELIVERED, RTS or CANCELLED, 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 returns 400 Shipment SHP-… not found.

    A realistic sequence for one shipment: create the order (shipment.dispatched) → DRIVER_ASSIGNED → TRANSIT → DELIVERED. Use a second shipment for TRANSIT → RTS, and cancel a third with POST /b2b/shipments/cancel/{shipmentCode} to receive shipment.cancelled.

  4. 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-id was stored, and sending the same event twice is processed once.
    • Your handler answered 200 in well under a second.
    • The shipment's status in your system matches data.status, and an older data.timestamp doesn't overwrite a newer one.
    • Events you don't handle still get 200.

    To test retries, make your handler return 503 once and watch the next attempt arrive about a second later with x-webhook-attempt: 2 and the same x-webhook-id.

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.success is true.
  • 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.
  • 2xx returned 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-2xx responses, and failureCount / backoffUntil from GET /b2b/webhook/info.

See Go live for the rest of the production checklist.

Was this page helpful?

On this page