Flexport Integration Deployment Canary

Overview

Keep deployment mechanics provider-neutral and Flexport validation surface-specific. A safe release proves secret injection, read-only access, version handling, webhook raw-body verification, and mutation gates before traffic expands.

Prerequisites

Immutable release artifact and reviewed configuration diff
Secret references supplied by the deployment platform, not command-line values
Read-only canary and tested rollback procedure

Instructions

Step 1: Classify the change

Label REST schema/version, OAuth credential, MCP tool/session, webhook receiver, or business-policy change and name its rollback unit.

Step 2: Validate offline

Run contract fixtures for documented success, additive fields, auth errors, webhook signatures, and ambiguous mutations.

Step 3: Deploy dark

Start the release with mutations disabled and no automatic booking, document creation, or record update.

Step 4: Run a read-only canary

Reuse a cached token and perform one approved shipment read or MCP tracking call. For receivers, send a signed synthetic fixture through the exact raw-body path.

Step 5: Expand gradually

Increase traffic by a reversible cohort while monitoring auth, permission, parsing, queue, duplicate, and reconciliation outcomes.

Step 6: Rollback on invariant breach

Restore the prior artifact/configuration together, preserve redacted evidence, and reconcile any ambiguous in-flight mutation.

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

A receiver release first validates a synthetic X-Hub-Signature-256 request, then receives a small traffic cohort. Any authentication or duplicate-rate regression routes callbacks back to the previous release.

Error Handling

Failure	Response
Secret absent	Fail startup; never accept an unauthenticated fallback.
Canary uses wrong account/version	Stop rollout and correct configuration identity.
Mutation occurs in dark mode	Disable the release and reconcile the resource immediately.
Rollback leaves queue split	Pause consumers and restore one authoritative ownership boundary.

flexport-deploy-integration