Skip to Content
FastracDocs

Webhooks

Get a signed HTTPS request from Shipping Engine every time one of your shipments changes.

Product
APIShipping Engine API
Section
Webhooks
Reading time
11 min read

Webhooks tell your system when a shipment moves, so you don't have to poll. When a courier picks up, delivers, cancels or returns a parcel, Shipping Engine sends a signed POST request to a URL you choose.

In short

  • You register one HTTPS endpoint per organisation with POST /b2b/webhook/setWebhook, together with a secret you generate.
  • Before saving it, Shipping Engine sends a challenge. Your endpoint must echo it back, or it receives no events.
  • Every event is signed with your secret. Verify the signature, answer 2xx quickly, and process the event in the background.

What you can use webhooks for

You want to…Listen for
Show "Shipped" with a tracking link as soon as the courier accepts the bookingshipment.dispatched
Tell the customer a driver is on the way (instant couriers)shipment.pending_pickup with driver fields
Update the order timelineshipment.in_transit, shipment.delivered
Stop fulfilment or contact the customershipment.cancelled, shipment.problem_detected, shipment.pickup_failed
Handle returnsshipment.rts_*
Reconcile your balanceshipment.price_changed, shipment.measurement_changed, shipment.rts_billed

The full list, with payloads, is in Events.

Set up your endpoint

  1. Generate a secret

    Create a random secret of at least 32 characters and store it in your secret manager. Shipping Engine uses it to sign every event, and you use it to check the signature. You choose it; Shipping Engine never shows it back to you.

    openssl rand -hex 32
    InboundOutput
    3f9c1d6e8a4b2f7c0e5d9a1b6c3f8e2d7a4b0c9e5f1d6a3b8c2e7f4a9d0b5c1e
  2. Build the endpoint

    Your endpoint must do two things:

    1. Answer the challenge. When you register, Shipping Engine sends an unsigned POST with the body {"challenge":"<uuid>"}. Reply with any 2xx status and the body {"challenge":"<uuid>"} (the same value), or just the raw value as plain text.
    2. Verify and accept events. Every event carries an x-webhook-signature header. Check it on the raw request body, reply 2xx, then process the event.

    A request without an x-webhook-signature header is the challenge. Everything else is an event.

    server.js (Express)
    import express from 'express';
    import crypto from 'node:crypto';
    
    const app = express();
    const SECRET = process.env.FASTRAC_WEBHOOK_SECRET;
    
    function isValidSignature(rawBody, headers) {
      const id = headers['x-webhook-id'];
      const timestamp = headers['x-webhook-timestamp'];
      const match = /sig=([0-9a-f]+)/.exec(headers['x-webhook-signature'] ?? '');
      if (!id || !/^\d+$/.test(timestamp ?? '') || !match) return false;
      if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
    
      const bodyHash = crypto.createHash('sha256').update(rawBody).digest('hex');
      const expected = crypto
        .createHmac('sha256', SECRET)
        .update(`${timestamp}.${id}.${bodyHash}`)
        .digest();
      const received = Buffer.from(match[1], 'hex');
      return received.length === expected.length && crypto.timingSafeEqual(received, expected);
    }
    
    // express.raw keeps the exact bytes Shipping Engine signed
    app.post('/webhooks/shipping-engine', express.raw({ type: '*/*' }), (req, res) => {
      if (!req.get('x-webhook-signature')) {
        const { challenge } = JSON.parse(req.body.toString('utf8') || '{}');
        return res.json({ challenge }); // the verification challenge
      }
    
      if (!isValidSignature(req.body, req.headers)) return res.sendStatus(401);
    
      res.sendStatus(200); // acknowledge first…
      const event = JSON.parse(req.body.toString('utf8'));
      queueForProcessing(req.get('x-webhook-id'), req.get('x-webhook-event-type'), event); // …work later
    });
    
    app.listen(3000);

    These handlers use one secret. To rotate secrets without downtime, select the secret by keyId, as shown in Verify signatures.

    Deploy the endpoint on a public HTTPS URL before you register it. For local development, see Testing webhooks.

  3. Register the endpoint

    Call POST /b2b/webhook/setWebhook with your URL and secret. Your API key needs the MANAGE_WEBHOOKS permission.

    curl -s -X POST "$FASTRAC_API/b2b/webhook/setWebhook" \
      -H "Authorization: Bearer $FASTRAC_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "Production order updates",
        "url": "https://shop.example.com/webhooks/shipping-engine",
        "secret": "'"$FASTRAC_WEBHOOK_SECRET"'",
        "keyId": "key-2026-11",
        "eventTypes": ["shipment.*"]
      }'
    FieldTypeRequiredDescription
    namestring, up to 100 charactersYesA label for your own reference.
    urlstringYesYour endpoint. Must start with https://.
    secretstring, at least 32 charactersYesThe signing secret you generated.
    keyIdstring, up to 64 charactersNoA name for this secret. It is sent in every signature header so you can tell secrets apart. Default: a generated value such as whsec_4f1c….
    eventTypesarray of 1–20 stringsNoWhich events to send. See Event filters. Default: ["shipment.*"].
    timeoutMsinteger, 1000–60000NoHow long Shipping Engine waits for your response, in milliseconds. Default: 10000 (10 seconds).
    maxAttemptsinteger, 1–50NoTotal delivery attempts per event, including the first. Default: 8. See Delivery and retries.
    InboundResponse (201)
    {
      "statusCode": 201,
      "message": "Webhook endpoint registered",
      "data": {
        "id": 42,
        "name": "Production order updates",
        "url": "https://shop.example.com/webhooks/shipping-engine",
        "isEnabled": true,
        "verificationStatus": "verified",
        "apiVersion": "V3",
        "timeoutMs": 10000,
        "maxAttempts": 8,
        "eventTypes": ["shipment.*"],
        "activeSecretKeyIds": ["key-2026-11"],
        "createdAt": "2026-11-20T03:12:09.511Z",
        "updatedAt": "2026-11-20T03:12:09.511Z",
        "backoffUntil": null,
        "failureCount": 0,
        "challenge": { "success": true, "statusCode": 200 }
      }
    }

    One endpoint per organisation

    Each organisation has one webhook endpoint. Calling setWebhook again replaces the URL, the secret, the keyId and the event filters immediately. There is no overlap period: from that moment every event is signed with the new secret. Fields you leave out keep a default (eventTypes, keyId) or their previous value (timeoutMs, maxAttempts).

  4. Check that verification passed

    Look at data.challenge.success and data.verificationStatus in the response. A 201 alone does not mean your endpoint works.

    ResultWhat it meansWhat to do
    challenge.success: true, verificationStatus: "verified"Your endpoint answered the challenge.Nothing. Events start flowing.
    challenge.success: false, verificationStatus: "failed" (HTTP 201)The endpoint was saved, but it receives no events.Read challenge.statusCode, challenge.responseBody or challenge.error, fix the endpoint, and call setWebhook again.
    HTTP 422 The webhook URL could not be verified. The current webhook endpoint stays active and unchanged.You already had a verified endpoint, and the new URL failed the challenge.Your old endpoint keeps working with its old secret. Fix the new URL and try again.
    InboundResponse when the challenge fails (201)
    {
      "statusCode": 201,
      "message": "Webhook endpoint registered",
      "data": {
        "id": 42,
        "verificationStatus": "failed",
        "challenge": {
          "success": false,
          "statusCode": 200,
          "responseBody": "{\"ok\":true}"
        }
      }
    }

    The challenge waits up to 10 seconds for your reply. A 2xx with the wrong body still fails. Typical causes: the route doesn't handle unsigned requests, a framework returns a fixed body, or a firewall blocks the request.

Event filters

eventTypes decides which events reach your endpoint. Each entry is a pattern:

PatternMatches
*Every event.
shipment.*Every shipment event (the default).
shipment.deliveredExactly that event.
*.deliveredAny event ending in .delivered: shipment.delivered, shipment.rts_delivered.
shipment.rts_*Every return (RTS) event, including shipment.rts_billed.

An event is sent if it matches any pattern in the list. Patterns are case-sensitive.

Tip

Start with shipment.* and ignore the events you don't need in your handler. If you subscribe to a short list instead, you won't receive events that are added later, such as shipment.status_updated.

Check your current endpoint

GET /b2b/webhook/info returns your endpoint (as a one-item array, or an empty array if none is registered). It needs the READ_WEBHOOKS permission.

curl -s "$FASTRAC_API/b2b/webhook/info" \
  -H "Authorization: Bearer $FASTRAC_TOKEN"
InboundResponse
{
  "statusCode": 200,
  "message": "Request successful.",
  "data": [
    {
      "id": 42,
      "name": "Production order updates",
      "url": "https://shop.example.com/webhooks/shipping-engine",
      "isEnabled": true,
      "verificationStatus": "verified",
      "apiVersion": "V3",
      "timeoutMs": 10000,
      "maxAttempts": 8,
      "eventTypes": ["shipment.*"],
      "activeSecretKeyIds": ["key-2026-11"],
      "createdAt": "2026-11-20T03:12:09.511Z",
      "updatedAt": "2026-11-20T03:12:09.511Z",
      "backoffUntil": null,
      "failureCount": 0
    }
  ]
}
FieldMeaning
isEnabledfalse if the endpoint has been disabled. No events are sent while it is disabled.
verificationStatusverified, failed or unverified. Only verified endpoints receive events.
activeSecretKeyIdsThe keyId of the secret that signs events. The secret itself is never returned.
failureCountConsecutive failed delivery attempts. Resets to 0 after any successful delivery.
backoffUntilIf set, deliveries are paused until this time. See Endpoint pause.

Both endpoints are also listed in the API reference.

Manage the endpoint in the dashboard

Business users can also manage the endpoint on the dashboard's API Integration page, under Webhook Configuration. They need the MANAGE_WEBHOOKS permission.

app.fastrac.cc/api-integration
Webhook Configuration card with one active webhook endpoint and the Register New Webhook form with name, HTTPS URL, HMAC secret key and the shipment.* event subscription
API Integration → Webhook Configuration in the dashboard.
  • Register New Webhook takes a Webhook Name, a Webhook URL (HTTPS Required) and an HMAC Secret Key of at least 32 characters (Auto-generate Secret creates one). The only event subscription offered is shipment.*. The challenge runs the same way as with the API. Registering again replaces the endpoint and its secret immediately.
  • Active Webhooks List shows the endpoint's name, URL, event filters and an Active label.
  • Delete removes the endpoint and stops webhooks completely. Register again to start over.

The dashboard doesn't set keyId, timeoutMs or maxAttempts (defaults apply), doesn't show verificationStatus, and can't disable an endpoint temporarily. Use the API to see or change these.

Endpoint requirements

RequirementDetails
HTTPS onlyThe URL must start with https://. Plain HTTP is rejected.
Valid certificateA certificate from a public certificate authority that matches the host name. Self-signed and expired certificates fail.
Public addressThe host must resolve to a public IP address. Private, loopback and link-local addresses (for example 10.x, 192.168.x, 127.0.0.1) are rejected.
No redirectsA 3xx response is not followed and counts as a failed delivery. Register the final URL.
Fast 2xxReply within timeoutMs (10 seconds by default). Connecting must take under 3 seconds.
Small responseShipping Engine reads at most 64 KB of your response body and ignores the rest. Return an empty body or a short JSON.

Next steps

Was this page helpful?

On this page