Open WebUI Integration

Connect your Open WebUI instance to Capsule Security for governance of every chat turn that passes through it - with inline policy enforcement before the model call, audit of prompts and responses after it, and an inventory of the workspace models, tools and functions your teams have built inside the tool.

This integration uses an Open WebUI Filter function that runs in-process inside your Open WebUI server. Before each user turn reaches the model, the filter posts it to your Capsule tenant and blocks on an allow/deny verdict. After the turn settles, it posts the assistant response and the tool set that was in play as fire-and-forget telemetry.

Open WebUI is operator-deployed - you run it in your own infrastructure, so there is no SaaS install. The only thing exchanged at install time is a signed token that scopes the filter to your tenant and environment.

Because Open WebUI passes the authenticated user and chat to every filter call, activity is attributed to the real user and the real conversation rather than to a shared service identity.

The following filter methods are configured:

Before you begin, ensure you have:

• A running Open WebUI instance (v0.5.0 or later)
• Administrator access to the Open WebUI Admin Panel
• A Capsule Security account with admin access
• Network access from your Open WebUI server to your Capsule agentsecurity endpoint (e.g. https://agents.capsule.security)

1. Log in to the Capsule Security portal.

2. Navigate to Integrations and locate Open WebUI.

3. Click Install - Capsule generates a JWT scoped to your tenant and Open WebUI environment. The token contains the tenant and environment claims required by the agentsecurity endpoint; treat it as a secret.

4. Copy the generated endpoint and token. You will paste both into the filter configuration in Step 3.

Open WebUI stores function source in its own database rather than on disk, so there is nothing to install on the host and no package to manage. Any Python dependencies the filter needs are declared in its frontmatter and installed by Open WebUI when the function loads.

1. In Open WebUI, navigate to Admin Panel > Functions.

2. Click + to add a function, then use Import from Link and paste the filter URL shown on the Capsule integration card. You can also paste the source directly.

3. Review the source before saving. The filter executes inside your Open WebUI server on every chat turn, so treat it the way you would treat any other function you install.

4. Save the function. It appears in the function list as Capsule Guard.

Saving activates the function immediately. Open WebUI does not need to be restarted.

The filter reads its configuration from Valves, Open WebUI's admin-scoped settings for a function. Keeping the token in a valve rather than in the source means you can rotate it without re-importing the filter.

1. In Admin Panel > Functions, click the settings icon on the Capsule Guard row.

2. Set capsule_endpoint to the endpoint from Step 1, for example https://agents.capsule.security/v1/openwebui/hooks/events.

3. Set capsule_token to the JWT from Step 1.

4. Save.

Valve values live in the Open WebUI database and are visible to any Open WebUI administrator. Treat the token accordingly:

• Restrict Open WebUI administrator access to the same set of people you would trust with a tenant-scoped API credential
• Rotate the token through the Capsule portal if an administrator leaves or if the value is exposed
• Never paste the token into the function source, into a shared config file, or into version control

A filter only applies to the models an administrator has enabled it on. To govern every model in the instance:

1. In Admin Panel > Functions, locate Capsule Guard.

2. Confirm the function is active.

3. Click the globe icon to toggle Global.

With Global enabled the filter runs on all models and cannot be disabled per model. Without it, coverage is limited to the models you enable it on individually, and any model added later is ungoverned until someone remembers to enable it.

1. Open a new chat in Open WebUI and send a message to generate activity.

2. Log in to the Capsule Security portal.

3. Navigate to Inventory > Agents and confirm an Open WebUI agent appears.

4. Click on the agent and review the audit logs to verify the user message and the assistant response are captured.

If events are not appearing:

1. Verify the endpoint is reachable from the Open WebUI host:

   curl -sS -o /dev/null -w "%{http_code}\n" https://agents.capsule.security/v1/openwebui/hooks/events

2. Verify the valves are set - the filter stays inert and logs capsule_guard: disabled when capsule_endpoint or capsule_token is missing.

3. Confirm the filter is enabled - an inactive function, or an active one that is neither global nor enabled on the model you are testing, never runs.

4. Check for timeouts - if your network has high latency to the Capsule endpoint, increase timeout_ms or confirm fail_open is set appropriately.

5. Check the Open WebUI server logs - the filter logs a warning on every failed post, including the HTTP status Capsule returned.

6. Contact Capsule Security support if issues persist.

The Capsule filter runs in-process inside your Open WebUI server and observes every chat turn. Before deploying:

1. Review the filter source before importing it. Open WebUI functions are arbitrary Python that runs on your server with access to the full request. This applies to the Capsule filter and to every other function you install.
2. Protect the JWT - anyone with the token can post events on behalf of your tenant. Rotate it through the portal if it is exposed.
3. Choose fail_open deliberately - true (the default) prioritizes availability and lets turns through when Capsule is unreachable; false prioritizes policy enforcement and rejects turns when Capsule cannot be reached.
4. Pin a filter version in production and review changes before re-importing.
5. Use TLS-only endpoints. The filter sends a Bearer token on every request - never configure an http:// endpoint outside local development.

For help with this integration:

• Email: support@capsule.security
• Include: Your organization ID, integration status, plugin version, and any error messages

• Open WebUI Documentation
• Open WebUI Plugin System
• Open WebUI Filter Functions