Flexport Webhooks Skill

When to Use This Skill

• Setting up Flexport webhook handlers
• Debugging Flexport signature verification failures (X-Hub-Signature-256)
• Understanding Flexport Event objects and milestone identifiers
• Handling shipment, shipment leg, container, document, invoice, and purchase order events

Verification (core)

Flexport signs the raw request body with HMAC keyed on your per-endpoint secret token and sends two GitHub/X-Hub-style headers, each a hex digest prefixed with the algorithm:

• X-Hub-Signature-256 — HMAC-SHA256, formatted sha256=<hex> (use this)
• X-Hub-Signature — HMAC-SHA1, formatted sha1=<hex> (legacy, being deprecated)

Verify against the raw UTF-8 body before parsing JSON, and compare timing-safe.

Node:

const crypto = require('crypto');

function verify(rawBody, signatureHeader, secret) {
  const [algo, sig] = (signatureHeader || '').split('=');
  if (algo !== 'sha256' || !sig) return false;
  const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  try {
    return crypto.timingSafeEqual(Buffer.from(sig, 'hex'), Buffer.from(expected, 'hex'));
  } catch {
    return false;
  }
}

Python:

import hmac, hashlib

def verify(raw_body: bytes, signature_header: str, secret: str) -> bool:
    algo, _, sig = (signature_header or "").partition("=")
    if algo != "sha256" or not sig:
        return False
    expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(sig, expected)

There is no official Flexport SDK, so verify manually in every framework.

For complete handlers with route wiring, event dispatch, and tests, see:

• examples/express/
• examples/nextjs/
• examples/fastapi/

Event Object & Dispatch

The delivered payload is a Flexport Event object. Dispatch on the type field, which holds the milestone identifier in /object#event format (note: /object#event, not object.event). The affected object is under data.

{
  "_object": "/event",
  "id": 123456,
  "version": 2,
  "created_at": "2026-07-23T10:00:00Z",
  "occurred_at": "2026-07-23T09:59:00Z",
  "type": "/shipment#created",
  "data": { "resource": { "...": "..." }, "shipment": { "...": "..." } }
}

Common Event Types

Only /shipment#created and /shipment_leg#departed are confirmed against Flexport's milestone reference. The other rows below are illustrative examples of the /object#event format — verify the exact identifiers against Flexport's milestone reference (or the events your account actually receives) before relying on them.

For the full milestone reference, see Flexport Webhook Endpoints. Some milestones are "available upon request".

Important Headers

Environment Variables

FLEXPORT_WEBHOOK_SECRET=your_secret_token   # Per-endpoint secret token set in Flexport account Settings

Local Development

# Start tunnel (no account needed)
npx hookdeck-cli listen 3000 flexport --path /webhooks/flexport

Reference Materials

• references/overview.md - Flexport webhook concepts and events
• references/setup.md - Configure endpoints and secret token in Settings
• references/verification.md - Signature verification details and gotchas