Integration Patterns

Integration Patterns

Choose the narrowest integration surface that fits the job. This keeps credentials, failure modes, and compatibility manageable.

Surface selection

Need	Prefer	Why
Human terminal investigation	CLI	Stable task-oriented commands and readable output
Agent-driven structured queries	MCP	Typed tools and explicit mutation policy
Custom application integration	REST API	Versioned request/response contract
Live browser/service updates	WebSocket	Push events without polling
Alert delivery	Webhooks	Purpose-built retries and delivery history
Operational metrics	Prometheus endpoint	Standard scrape and aggregation model
Historical migration	Export/import	Supported, idempotent data transfer

Read path before write path

Build integrations in stages:

1. authenticate and call health;
2. perform a bounded read;
3. handle pagination, timeouts, and errors;
4. add observability and redaction;
5. introduce one idempotent mutation if necessary;
6. verify the resulting state;
7. document recovery and credential rotation.

Identity and idempotency

Persist stable CCAM IDs rather than matching sessions only by name or path. Remote sources and multiple providers can produce similar display labels. Downstream webhook consumers should deduplicate retries and tolerate out-of-order delivery.

Authentication boundaries

Use the dashboard token for REST/WebSocket clients, the hook token for remote producers, and the MCP HTTP token for MCP transport. Store secrets in a secret manager or restricted file and redact request headers from logs.

Version compatibility

Pin automation to a CCAM release and validate against that release's API, CLI, or MCP reference. Detect unknown fields permissively, but do not assume missing capabilities.

Failure behavior

Set bounded timeouts and retries with backoff. Do not make Claude Code or Codex execution depend synchronously on a monitoring integration. Queue optional downstream work and preserve the originating session/event ID for replay.