Deploying an Integration

This page covers the customer side of a release: connecting a worker, agent, CI job, or scheduled process to the hosted ActionBox API. The hosted endpoints are already managed for you.

Release checklist

• Use https://api.actionbox.cloud as the API base URL.
• Keep a separate axb_test_... key for protocol checks and an axb_live_... key for real work.
• Load credentials from your deployment secret manager, never from source control, client-side JavaScript, or an image layer.
• Give every create request a stable Idempotency-Key; use a separate dedupe_key when repeated events should converge on one open Action.
• Decide how the caller resumes: signed callback, polling, CLI wait, or an SDK helper. Keep polling as the recovery path even when callbacks are enabled.
• If you use a callback, make it public HTTPS, credential-free, and ready to verify the ActionBox signature before launch.
• Store and present the returned action_version and fingerprint with the review snapshot.
• After execution, report exactly one immutable success or failed outcome bound to that version and fingerprint.
• Alert on authentication failures, quota/rate-limit responses, terminal callback failures, and stale Watch incidents.

Configure the client

Use placeholders in deployment configuration and inject the real value at runtime:

export ACTIONBOX_API_URL="https://api.actionbox.cloud"
export ACTIONBOX_API_KEY="<source-key-from-your-secret-manager>"

Do not print these variables in CI logs. A live Source key is scoped to one Source and environment; it cannot read or resolve another Source's Actions.

Verify safely with a test key

In the hosted production service, test-key requests use the same Action contract while remaining isolated from live Actions, live billing usage, the default inbox, push hints, and terminal callbacks. They are useful for checking authentication, idempotency, typed responses, and client error handling. Test Actions are not a substitute for a controlled live release check.

When the protocol check is complete, revoke or rotate the test key and remove its value from temporary logs and CI output. Never use a live customer Action to probe a new deployment.

Connect the decision loop

1. Create an Action with a stable title, concise context, and optional callback_url.
2. Persist the returned action_id, action_version, and fingerprint.
3. Let an authorized human choose a typed response.
4. Fetch or receive the terminal Action, verify its version-bound snapshot, and execute the downstream operation only for the response your policy accepts.
5. Post one execution outcome with the exact version and fingerprint.

An open Action can still change. A decision against a stale material snapshot fails closed with 409 ACTION_CHANGED; fetch the current Action and require a fresh review. resolved means that authority or a response was recorded—it does not mean the downstream operation succeeded.

Callback preflight

Before enabling a callback in production, confirm that the receiver:

• accepts only the expected public HTTPS route and does not require a query credential;
• verifies the raw body and X-Actionbox-Signature before JSON parsing;
• rejects stale timestamps and deduplicates the stable event id;
• returns a quick 2xx after durable acceptance; and
• can safely process an at-least-once retry.

ActionBox does not follow redirects. Network errors, timeouts, 429, and 5xx responses are retried; other non-2xx responses fail the delivery. A callback failure never reverses a human decision. See Webhook operations.

CI and rollback behavior

Keep your ActionBox integration behind the same release gate as the operation it protects:

• validate the request schema and destination configuration before rollout;
• deploy code that can read the previous response shape during a rolling release;
• fail closed when ACTION_CHANGED, ACTION_NOT_OPEN, or a receipt check indicates a stale decision;
• report a failed execution outcome rather than silently retrying a destructive operation; and
• retain the previous client version until callbacks and open Actions drain.

For a client rollback, stop creating new live Actions, let or reconcile open Actions using the last known contract, then restore the previous client. Do not turn an API timeout into an automatic rejection unless that policy is explicit in your own system.

Final smoke check

The hosted liveness and readiness URLs can confirm that the public API is reachable:

curl -fsS https://api.actionbox.cloud/health
curl -fsS https://api.actionbox.cloud/ready

These unauthenticated checks do not prove that your Source key, callback, workspace permissions, quota, or Watch evaluator is configured correctly. For an integration issue, capture the HTTP status, stable error code, resource ID, timestamp with timezone, and X-Request-ID. Redact keys, callback URLs, heartbeat URLs, Action content, and customer data.