Secure AI chat widget architecture
Tenant isolation, CSP discipline, webhook validation, signed outbound, audit-grade transcripts. The architecture that lets a buyer's security team sign off without exceptions.
Most chat widgets are a security afterthought
Common chat widgets ship 200+ KB of JavaScript, leak host-page DOM state, demand permissive CSP directives, and don't sign their outbound calls. For a buyer's security team, that's a checklist of red flags.
This guide covers the architecture decisions that make a chat widget defensible: tenant isolation, CSP discipline, webhook validation, signed outbound, and audit-grade transcripts.
One widget, many tenants, zero crossover
- Per-tenant data plane. Conversations, configurations, and audit live in a tenant-scoped state layer.
- Per-tenant credentials. Provider keys, AI keys, webhook secrets are scoped to one tenant. Cross-tenant access is impossible by construction.
- Per-tenant locks. Conversation lock state is held in the tenant's data plane. No global lock contention.
- Per-tenant retention. Retention windows configurable per channel and policy.
Strict CSP-friendly bootstrap
The widget loader is small (2.4 KB), signed, and shipped from a versioned CDN. Recommended CSP additions for buyers:
script-src: add the widget CDN host (no wildcards).
connect-src: add the API host.
style-src: the widget bundles its own styles in a strict bundle.
frame-src / frame-ancestors: not needed unless using iframe variant; in that case, allow only the widget origin.
Avoid unsafe-inline and unsafe-eval. The widget runs without either.
Inbound and outbound signed end-to-end
- Inbound provider webhooks. Verified with raw-body HMAC (X-Hub-Signature-256 for Meta, channel secret for LINE, idempotency key for Shopify).
- Outbound platform webhooks. Signed with X-IB-Signature using a per-tenant shared secret. Idempotency key included.
- Verify before processing. Mismatched signatures are dropped at the edge before the request enters the data plane.
Every action is reproducible
The Wake captures every routing decision, AI tool call, knowledge lookup, handoff, agent reply, supervisor action, export, and admin operation. Each entry includes timestamp, actor, conversation ID, and reason. Replay supports training, dispute resolution, and compliance review. Exports are tamper-evident.
Frequently asked questions
What CSP directives does the widget need?
At minimum: a script-src for the loader's CDN, a connect-src for the API host, and a style-src that the widget's bundle is built against. Specific directives are documented in the dashboard for the buyer's CSP team.
Does the widget run in an iframe?
The chat UI is rendered in an isolated container with strict CSS isolation. Cross-origin iframe alternatives are available for buyers who require stronger sandboxing; both options are documented.
How are messages signed?
Outbound webhook calls from the platform are signed with X-IB-Signature using HMAC. Inbound provider webhooks (WhatsApp, Telegram, Meta, LINE, Shopify) are verified with raw-body provider signatures.
Keep exploring
Bring your security checklist.
We'll walk through the architecture, CSP directives, and audit posture during a security-review demo. Procurement-friendly artifacts available on request.