How AI agents safe
communicate
with external systems
API integrations, webhooks, CRM and service boundaries on the OpenClaw Gateway — structured execution, retries with caps, and integration governance in production.
direct answer
What are API integrations
within OpenClaw?
Short answer: Defined connections that allow agents to communicate with external systems via tools, REST, and webhooks — inbound events in queues, outbound calls with schedule, retries, and governance.
Nuance: in addition to classic APIs, also webhooks, Browser tools where there is no API, CRM/mail integrations, and the same approvals/retry discipline as internal tools.
Landscape
Which systems AI agents connect to
No “thousands of apps” — deliberate service boundaries per workflow.
CRM systems
HubSpot, Pipedrive, custom REST — mutating writes are high-risk; read-only triage first.
Mailbox providers
IMAP/SMTP/API mail — wide scope = wide failure blast radius.
Slack / Discord
Channel bots, slash commands — inbound webhooks + outbound posts; rate limits per workspace.
Browser services
SaaS without a stable API → Browser automation as a fallback, harder to govern.
Monitoring & ticketing
PagerDuty, Jira, Linear — event-driven escalations; strictly validate payload schema.
Internal APIs
LAN/VPC services — service boundaries and mTLS where possible.
External APIs
Third-party quotas, breaking schema changes — contract testing on staging.
Upstream LLM providers
Anthropic/OpenAI-compatible/Ollama — see also API for inference routing.
Execution
Webhooks & structured execution
webhooks
Inbound events to Gateway queue — signature verify, replay protection, idempotency key per event ID.
Retries
Exponential backoff + max attempts; no unbounded retry on mutating CRM/mail.
idempotency
Client-supplied idempotency header of dedupe on external event ID — prevents duplicate actions during webhook redelivery.
Structured execution
Tool calls with typed payloads, not free strings to shell — see Agent Tools.
Payload validation
JSON schema reject before queue — malformed payloads not pass to agent context.
Queueing
Webhook → queue → worker — burst events not directly to LLM. See Scaling & workers.
Event-driven flows
Trigger in workflows — explicit step boundaries and approval on mutating follow-up.
Failures
When API integrations go wrong
Retry storms
Scenario: 429 of CRM → all workers retry parallel without cap.
Impact: Rate ban; queue congestion; duplicate records.
Duplicate actions
Scenario: Webhook redelivery without idempotency — second ticket/update.
Impact: Data inconsistency; support load.
Malformed payloads
Scenario: Vendor changes field — agent receives partial JSON in prompt.
Impact: Silent wrong tool args; destructive call risk.
Steel data
Scenario: Agent makes decision based on cached CRM snapshot while record has already been modified.
Impact: Overwrite conflict; incorrect customer action.
Expired credentials
Scenario: OAuth refresh fails — tools fail with generic errors.
Impact: Looks like “AI broken”; retries worsen.
Webhook loops
Scenario: Outbound webhook triggers inbound webhook to the same endpoint.
Impact: Runaway queue; costs and rate limits.
governance
Integration security
API keys & secrets
Per integration scope; never in agent channels or debug logs.
least privilege
Read-only tokens where possible; write scopes per workflow class.
Approval gates
Mutating API calls behind approvals — same discipline as email/browser.
RBAC
Who is allowed to trigger which integration — RBAC & permissions.
Logging & audit trails
request-id, integration-id, outcome — no full PII payloads in INFO. See logs.
Integration isolation
Separate credentials and queues per tenant/vendor — limit cascading failure.
Risk
External system
risks
Short answer: Integrations shift failures to customer data and reputation — not just to your Gateway uptime.
- → Mailbox integrations: Send scope + webhook triggers — combination of inbound event and autonomous reply.
- → CRM writes: Delete/update without idempotency — rollback in CRM ≠ rollback in agent audit.
- → Browser integrations: API gap filled with DOM — different failure mode than REST retries.
- → Destructive API actions: Bulk delete, merge — explicit approval + dry run on staging.
- → Credential leakage: Agent applies debug output in Slack — token in channel history.
- → Cross-system escalation: Ticket webhook → mail send → CRM update — chain without a single correlation ID.
One integration ID per vendor · readonly default · write via approval · correlation ID over webhook → queue → tool → audit.
Production
Integration
checklist
Pragmatism
When integrations become too complex
In short: Fewer couplings with better boundaries beat more adapters without observability.
Too many interconnected systems
Ten vendors without a service map — no one knows which webhook starts which workflow.
Orchestration complexity
Multi-hop without Orchestration governance — debug time explodes.
Debugging problems
No correlation ID across CRM + mail + Slack — incident becomes a whack-a-mole.
Hidden dependencies
Silent order assumptions (CRM before mail) — fails on queue reorder.
Cascading failures
One vendor down → retry storm → other integrations also 429.
Short answer: Structured connections between the Gateway/agents and external systems via tools, REST, webhooks, and event queues — with governance, not “hanging everything on Zapier”.
Nuance: Distinguish between inbound webhooks and outbound tool calls; browser as a last resort.
Follow-up: workflows · Agent Tools
Short answer: External systems push events — without validation and a queue, that becomes a direct agent trigger without backpressure.
Risk: loops, duplicate delivery, burst overload.
Advice: verify signature → validate schema → queue → worker.
Short answer: Idempotency keys, dedupe on event id, task locking on resource id, max retries with dead letter.
Cause: webhook redelivery + no idempotency.
Follow-up: queues
Short answer: 429 must reduce backoff and concurrency — do not retry harder; otherwise retry storm and longer ban.
Observability: per-integration 429 metric.
Follow-up: Monitoring
Short answer: Mutating calls (CRM update, mail send) are not safe-to-retry without idempotency — double side effects.
Fix: classify readonly vs mutating; cap returns; dead letter.
Follow-up: approvals on mutating
Short answer: Scoped secrets in env/vault, per integration rotation, never in logs/channels, RBAC on who is allowed to configure integrations.
Cause: debug dump to Slack.
Follow-up: RBAC
Short answer: If you can no longer track an incident with a single correlation ID, or >5 systems without service boundaries and fallbacks.
Advice: reduce connections; document event map; staged rollout per vendor.
Follow-up: Orchestration
Integration hardening
Integration audits &
Workflow governance
We review webhook flows, idempotency, credential scope, approval gates, and rate-limit behavior on your OpenClaw integrations — structured execution with audit trails, no adapter spaghetti.