Skip to main content

Prepare an API integration for production

Use this checklist after a workflow works against preview and before it handles production orders, shipments, or tracking events.

Separate preview and production​

ProductPreviewProduction
Hub APIhttps://api-test.orderly-hub.com/api/v1https://api.orderly-hub.com/api/v1
Intelligencehttps://api-staging.orderlycore.com/v1https://api.orderlycore.com/v1

Keep base URLs, credentials, and organization IDs in environment-specific configuration. Do not infer production values from preview or reuse preview keys.

Harden authentication​

  1. Create a dedicated API key for the integration.
  2. Grant only the scopes required by its current endpoints.
  3. Store the key in a secrets manager, never in source control or browser code.
  4. Record the owner and expiry date.
  5. Define rotation before the first emergency requires it.
  6. Revoke preview and test keys that are no longer used.

Always send X-Organization-Id when the endpoint is organization-scoped. Treat the organization ID as configuration, not user input.

Set safe request behavior​

  • Use explicit connection and response timeouts.
  • Retry 429 and transient 5xx responses with exponential backoff and jitter.
  • Respect Retry-After when it is present.
  • Do not automatically retry a write unless the endpoint and your workflow make the operation safe to repeat.
  • Put a maximum attempt count and total retry window on every retry policy.
  • Validate response envelopes before reading data.

Hub list endpoints use a { data, pagination } shape. Intelligence responses use { ok, data, meta } and include a request ID in meta.

Handle pagination and volume​

Never assume the first page is the complete dataset.

  1. Set an intentional page size.
  2. Follow pagination until the expected end condition.
  3. Process pages incrementally rather than holding an unbounded result in memory.
  4. Store a checkpoint for long-running synchronization.
  5. Use source timestamps or supported filters for incremental reads.

Test with production-like volume in preview, including empty pages and records that change during the sync.

Make webhooks resilient​

  • Expose a public HTTPS endpoint.
  • Verify the signature before trusting the payload.
  • Preserve the raw body required by signature verification.
  • Return 2xx quickly, then process asynchronously.
  • Deduplicate repeated deliveries.
  • Make handlers safe when events arrive late or out of order.
  • Log the event type, organization, entity ID, and processing result.
  • Keep a replay or recovery path when downstream processing fails.

Webhook delivery retries do not replace your own dead-letter and recovery strategy.

Log for support and recovery​

For every API call, record:

  • product and endpoint,
  • organization ID,
  • response status,
  • request ID,
  • attempt number and duration,
  • safe entity identifiers,
  • final outcome.

Never log API keys, bearer tokens, carrier credentials, webhook secrets, or unnecessary customer data.

Monitor the business outcome​

Technical success is not enough. Alert when:

  • order or tracking volume unexpectedly drops,
  • a sync checkpoint stops advancing,
  • webhook failures increase,
  • 401, 403, 429, or 5xx responses cross a threshold,
  • Intelligence feed lag or unknown-code rate rises,
  • a write workflow creates duplicates or partial results.

Connect operational alerts to an owner and a documented response.

Rehearse failure​

Before launch, test:

  1. expired or revoked credentials,
  2. wrong organization ID,
  3. API timeout,
  4. rate limiting,
  5. temporary 5xx,
  6. duplicate webhook delivery,
  7. out-of-order events,
  8. partial downstream failure,
  9. rollback or replay.

Use Troubleshoot Orderly as the starting runbook, then add integration-specific commands and ownership.

Launch checklist​

  • Preview and production configuration are separate.
  • Least-privilege production credentials are stored securely.
  • Timeouts, bounded retries, and pagination are implemented.
  • Write retries and webhook delivery are safe to repeat.
  • Logs include request IDs without secrets.
  • Technical and business-volume alerts have owners.
  • Failure and rollback procedures were rehearsed.
  • The first production run has a narrow scope and active monitoring.