Flexport Production Checklist

Overview

Pre-deployment and go-live checklist for Flexport logistics integrations covering API configuration, webhook setup, monitoring, and rollback procedures.

Prerequisites

• A launch owner, approver, rollback operator, approved data-flow inventory, and staging evidence using fictional shipments.
• Redacted monitoring, explicit target/destination policies, and a secure path for credentials and incident evidence.

Instructions

1. Attach evidence or an owner decision for every applicable checklist control; leave no implicit acceptance.
2. Verify scoped secrets, signature validation, idempotent processing, redacted diagnostics, and retention/access behavior.
3. Run a small staging or production canary with synthetic data and observe aggregate health, queue, and delivery outcomes.
4. Stop promotion and invoke rollback on permission, policy, integrity, or safety thresholds; record the decision and recovery test.

Output

Create a go-live receipt with completed controls, evidence links, canary metrics, exceptions, approver, launch/rollback owners, and follow-up dates. Keep documents, addresses, commercial terms, and credentials out of it.

Error Handling

• Pause unsafe automation or notifications on signature, permission, destination, or reconciliation failures.
• Quarantine failed work by opaque ID and rotate credentials if exposure is possible.
• Confirm rollback and no unintended replay before resolving the launch incident.

Examples

Process a fictional shipment milestone through the canary, revoke a test destination’s access, and simulate an upstream outage. Promote only after the designated approver records that the handler paused safely, produced redacted metrics, and rolled back cleanly.

Pre-Deployment

Authentication & Secrets

• Production API key stored in secret manager (not env files)
• Webhook secret configured and verified
• Key rotation procedure documented
• No keys in git history (git log -p | grep -i flexport_api)

API Integration

• All endpoints tested against production API
• Pagination implemented for list endpoints (/shipments, /products)
• Rate limit handling with exponential backoff
• Retry logic for transient 5xx errors
• Idempotency keys on POST/PATCH operations
• Flexport-Version: 2 header on all requests

Webhooks

• HTTPS endpoint with valid TLS certificate
• X-Hub-Signature verification implemented
• Webhook endpoint responds within 5 seconds
• Dead letter queue for failed webhook processing
• Idempotent webhook handlers (replay-safe)

Data Integrity

• HS codes validated against customs requirements
• UN/LOCODE port codes verified
• Commercial invoice totals cross-checked
• Product catalog synced with Flexport Product Library

Monitoring & Alerting

// Health check endpoint
app.get('/health', async (req, res) => {
  const start = Date.now();
  try {
    const r = await fetch('https://api.flexport.com/shipments?per=1', {
      headers: {
        'Authorization': `Bearer ${process.env.FLEXPORT_API_KEY}`,
        'Flexport-Version': '2',
      },
    });
    res.json({
      status: r.ok ? 'healthy' : 'degraded',
      flexport: { connected: r.ok, latencyMs: Date.now() - start },
    });
  } catch {
    res.status(503).json({ status: 'unhealthy', flexport: { connected: false } });
  }
});

Alert Thresholds

Metric	Warning	Critical
API error rate	> 5%	> 20%
p99 latency	> 3000ms	> 10000ms
429 rate limits	> 5/hour	> 20/hour
Webhook failures	> 2/hour	> 10/hour
Auth failures (401/403)	Any	Any

Rollback Procedure

# Immediate rollback
kubectl rollout undo deployment/flexport-integration
# Or for non-k8s: revert to last known good image/version

Resources

• Flexport Status
• Flexport API Reference

Next Steps

For version upgrades, see flexport-upgrade-migration.