Webhook channel for n8n agents: HTTP endpoint with OpenAI Responses API subset

What they did

The author added a new webhook channel to n8n agents so an external backend can send a message to a published agent over HTTP and get the reply in the same response. The endpoint uses a subset of the OpenAI Responses API, so an OpenAI SDK client can call it by setting the base URL to the agent webhook URL. A request sends `input` as a string and an optional `conversation` as a string or `{ id }`; agent memory keeps the conversation, so the caller sends only the new message. The endpoint ignores `model`, refuses `stream: true`, and returns errors in the OpenAI error shape (400, 401, 403, 404, 409, 500). The work was split into seven commits, each with passing tests. First, the author replaced the shared channel assumption that every channel except n8n Chat holds a credential and runs a Chat SDK runtime with two predicates (`hasChannelRuntime`, `integrationNeedsCredential`) and an `acceptedCredentialTypes` hook, without changing existing channel behavior. Then they added the `webhook` channel type and settings (`authentication`: `none`, `headerAuth`, `jwtAuth`), with drafts when settings are missing and copies/imports dropping settings. Next came `N8N_AGENT_WEBHOOK_URL` and `N8N_ENDPOINT_AGENT_WEBHOOK`, a URL service method, and a REST route for the editor; the URL never falls back to the webhook URL because webhook processes do not serve this endpoint. Then the public route and service that runs the published agent for one request, checking the conversation, refusing a second turn in the same conversation (409), stopping the run on caller disconnect, and returning 500 on tool approval. Unknown routes and invalid JSON also get the OpenAI error shape, and the endpoint path setting refuses collisions with other n8n paths. Header and JWT auth followed, comparing header values in constant time and verifying JWTs only with the credential's algorithm and public key for PEM. Finally, the setup stepper and edit view, sessions filter entry, catalog visibility, and MCP tool support (`update_agent_integration`, `discover_agent_assets`) for webhook channels without a credential. The author documented a manual test path: create an agent with a model and memory on, add the Webhook channel with None auth, copy the endpoint URL, publish, then curl two messages passing the `conversation.id` back. They also showed the OpenAI SDK with the URL without `/responses` as base URL, Header Auth returning 403 without the header and 200 with it, JWT Auth returning 401 without a bearer token and 403 for wrong key, wrong algorithm, or `alg: none`, plus error checks for `stream: true` (400), unknown conversation (404), parallel turns (409), and unpublished agent (404). Sessions can be filtered by Webhook origin, and the MCP server can set up the channel.

How it went

The PR landed as a seven-commit feature with tests passing after each commit, covering the channel config, endpoint, auth modes, setup UI, and MCP tools. The author verified behavior manually with curl and the OpenAI SDK, including the error shapes and auth failures. The checklist items (docs, backport labels) were left unchecked in the post, so docs follow-up and release labeling were still open.

Worth knowing

Only main instances serve the endpoint, and the URL never falls back to the webhook URL. Tool approval ends the turn with a 500 because approvals come later. There is no Chat Completions-compatible endpoint, since Chat Completions sends the full message list while this channel keeps conversation in agent memory. Copies and imports of an agent drop the webhook settings, so the copy needs setup before it can answer. The agent needs memory turned on to keep conversations. Screenshots of the setup stepper and edit view were still to be added, and docs/backport checklist items were unchecked.

Wiring

Set `N8N_AGENT_WEBHOOK_URL` and `N8N_ENDPOINT_AGENT_WEBHOOK` in the environment; the endpoint is served only by main instances at `{N8N_AGENT_WEBHOOK_URL}/{N8N_ENDPOINT_AGENT_WEBHOOK}/{agentId}/responses`. In the agent builder, open the agent's channels, add Webhook, choose authentication (None, Header Auth with an `httpHeaderAuth` credential, or JWT Auth with a `jwtAuth` credential), copy the endpoint URL, and publish. The agent must have a model and memory enabled. Callers POST JSON with `input` and optionally `conversation`; for the OpenAI SDK, set `baseURL` to the URL without `/responses` and pass the JWT as `apiKey`. The REST route gives the editor the URL, and the MCP server exposes `discover_agent_assets` (kind: integrations) and `update_agent_integration` (type: webhook, settings: { authentication: 'none' }).

Try it yourself

Add a webhook channel to our agent platform so an external backend can call a published agent over HTTP and get the reply in the same response. Use a subset of the OpenAI Responses API: accept `input` as a string and optional `conversation` as a string or `{ id }`, keep conversation state in agent memory, ignore `model`, reject `stream: true` with 400, and return errors in the OpenAI error shape (400, 401, 403, 404, 409, 500). Support three auth modes: none, Header Auth using an httpHeaderAuth credential with constant-time comparison, and JWT Auth using a jwtAuth credential that verifies only the credential's algorithm and uses only the public key for PEM. Serve only on main instances at `{N8N_AGENT_WEBHOOK_URL}/{N8N_ENDPOINT_AGENT_WEBHOOK}/{agentId}/responses`, with no fallback to the webhook URL. Refuse a second turn in the same conversation with 409, stop the run when the caller disconnects, and return 500 on tool approval. Add a setup stepper and edit view, a sessions filter entry, and MCP tool support for connecting a webhook channel without a credential. Split the work into commits that each keep tests passing, and add tests for auth, error shapes, and conversation handling.