Flexport Webhook Integrity and Reconciliation

Overview

Authenticate before parsing. Flexport documents both SHA-1 and SHA-256 signatures, with SHA-256 recommended in X-Hub-Signature-256; compare against the raw UTF-8 body and treat webhook delivery as a notification that may require API reconciliation.

Prerequisites

• Unique receiver URL and high-entropy webhook secret
• Framework support for raw request bytes before JSON parsing
• Allowlisted slash/hash event types and idempotency store

Instructions

Step 1: Register deliberately

Configure the callback and secret in Flexport account Settings. Record the intended event types and owner.

Step 2: Capture raw bytes

Read the exact request body before middleware transforms encoding or JSON layout.

Step 3: Verify SHA-256

Compute HMAC-SHA256 with the stored secret, parse X-Hub-Signature-256, reject malformed or unequal-length inputs, and use constant-time comparison.

Step 4: Acknowledge quickly

After authentication and durable enqueue, return HTTP 200 promptly. Keep business processing out of the request path.

Step 5: Deduplicate and route

Use provider event identity when present or a stable payload digest. Allow only documented names such as /shipment#created or /purchase_order#updated.

Step 6: Reconcile gaps

Use authorized REST /events or resource reads when evidence indicates a delivery gap; do not invent a webhook replay endpoint or retry schedule.

Authentication

REST calls authenticate with a cached OAuth 2.0 client-credentials Bearer token using audience https://api.flexport.com, or an explicitly accepted broad API key. Use distinct credentials per workload and never log credentials or tokens. MCP calls use the authenticated connection to https://mcp.flexport.com/mcp and remain subject to each tool's documented account permissions.

Tool Discipline

Use Read and Grep for discovery and evidence. Use Write or Edit only for the approved artifact, code, configuration, test, or receipt described by this workflow; do not make an unapproved Flexport-side change.

Output

• Scoped decision or implementation artifact
• Redacted operation and validation receipt
• Failure, rollback, and follow-up ownership record

Return a machine-reviewable receipt in this shape; adapt the operation values, but never place credentials or provider payloads in it:

surface: rest-v3
operation: shipment-read
decision: approved
outcome: verified
evidence:
  release_sha: recorded-out-of-band
  provider_reference: redacted
rollback_owner: logistics-platform

Examples

The receiver verifies X-Hub-Signature-256 over untouched bytes, durably enqueues /shipment_leg#departed, returns 200, and lets a worker reconcile the referenced shipment before updating local state.

Error Handling

Failure	Response
Signature missing or malformed	Return an authentication failure and store no payload.
Digest lengths differ	Reject before constant-time comparison rather than throwing.
Unknown event type	Quarantine metadata and compare with current event documentation.
Duplicate delivery	Return success after confirming the prior durable operation.

Resources

• First-party source notes
• Webhook endpoints
• Events
• Milestones