From 1f945383a0ea1fc160f6a6b8a054d72f4875cdea Mon Sep 17 00:00:00 2001 From: DrMelone <27028174+Classic298@users.noreply.github.com> Date: Thu, 12 Feb 2026 22:15:13 +0100 Subject: [PATCH] event docs message id event emitter --- docs/features/plugin/development/events.mdx | 22 +++++++++++++++------ docs/getting-started/env-configuration.mdx | 10 +++++++++- 2 files changed, 25 insertions(+), 7 deletions(-) diff --git a/docs/features/plugin/development/events.mdx b/docs/features/plugin/development/events.mdx index 31b141e9..de3b5229 100644 --- a/docs/features/plugin/development/events.mdx +++ b/docs/features/plugin/development/events.mdx @@ -30,7 +30,7 @@ Events are **fully available** for native Python Tools and Functions defined dir ### External Tools (OpenAPI & MCP) -External tools can emit events via a **dedicated REST endpoint**. Open WebUI passes the following headers to all external tool requests: +External tools can emit events via a **dedicated REST endpoint**. Open WebUI passes the following headers to all external tool requests when `ENABLE_FORWARD_USER_INFO_HEADERS=True` is set: | Header | Description | |--------|-------------| @@ -467,14 +467,24 @@ Yes—emit `"chat:message:delta"` events in a loop, then finish with `"chat:mess External tools (OpenAPI and MCP servers) can emit events to the Open WebUI UI via a REST endpoint. This enables features like status updates, notifications, and streaming content from tools running on external servers. +### Prerequisites + +To receive the chat and message ID headers, you must enable header forwarding by setting the following environment variable on your Open WebUI instance: + +``` +ENABLE_FORWARD_USER_INFO_HEADERS=True +``` + +Without this, Open WebUI will not include the identification headers in requests to external tools, and event emitting will not work. + ### Headers Provided by Open WebUI -When Open WebUI calls your external tool, it includes these headers: +When Open WebUI calls your external tool (with header forwarding enabled), it includes these headers: -| Header | Description | -|--------|-------------| -| `X-Open-WebUI-Chat-Id` | The chat ID where the tool was invoked | -| `X-Open-WebUI-Message-Id` | The message ID associated with the tool call | +| Header | Description | Env Var Override | +|--------|-------------|------------------| +| `X-Open-WebUI-Chat-Id` | The chat ID where the tool was invoked | `FORWARD_SESSION_INFO_HEADER_CHAT_ID` | +| `X-Open-WebUI-Message-Id` | The message ID associated with the tool call | `FORWARD_SESSION_INFO_HEADER_MESSAGE_ID` | ### Event Endpoint diff --git a/docs/getting-started/env-configuration.mdx b/docs/getting-started/env-configuration.mdx index f6fc962a..f89e91ea 100644 --- a/docs/getting-started/env-configuration.mdx +++ b/docs/getting-started/env-configuration.mdx @@ -1357,8 +1357,9 @@ If enabled, the following headers are forwarded: - `X-OpenWebUI-User-Email` - `X-OpenWebUI-User-Role` - `X-OpenWebUI-Chat-Id` + - `X-OpenWebUI-Message-Id` -This enables per-user authorization, auditing, rate limiting, and request tracing on external services. +This enables per-user authorization, auditing, rate limiting, and request tracing on external services. The chat and message ID headers are also required for [external tool event emitting](/features/plugin/development/events#-external-tool-events). #### `FORWARD_USER_INFO_HEADER_USER_NAME` @@ -1390,6 +1391,12 @@ This enables per-user authorization, auditing, rate limiting, and request tracin - Default: `X-OpenWebUI-Chat-Id` - Description: Customizes the header name used to forward the current chat/session ID. +#### `FORWARD_SESSION_INFO_HEADER_MESSAGE_ID` + +- Type: `str` +- Default: `X-OpenWebUI-Message-Id` +- Description: Customizes the header name used to forward the current message ID. This header is required for [external tool event emitting](/features/plugin/development/events#-external-tool-events). + :::tip Custom Header Prefix Use these variables when integrating with services that require specific header naming conventions. For example, AWS Bedrock AgentCore requires headers prefixed with `X-Amzn-Bedrock-AgentCore-Runtime-Custom-`: @@ -1399,6 +1406,7 @@ FORWARD_USER_INFO_HEADER_USER_ID=X-Amzn-Bedrock-AgentCore-Runtime-Custom-User-Id FORWARD_USER_INFO_HEADER_USER_EMAIL=X-Amzn-Bedrock-AgentCore-Runtime-Custom-User-Email FORWARD_USER_INFO_HEADER_USER_ROLE=X-Amzn-Bedrock-AgentCore-Runtime-Custom-User-Role FORWARD_SESSION_INFO_HEADER_CHAT_ID=X-Amzn-Bedrock-AgentCore-Runtime-Custom-Chat-Id +FORWARD_SESSION_INFO_HEADER_MESSAGE_ID=X-Amzn-Bedrock-AgentCore-Runtime-Custom-Message-Id ``` :::