n8n 에이전트용 웹훅 채널: OpenAI Responses API 서브셋을 지원하는 HTTP 엔드포인트

What they did

작성자는 외부 백엔드가 HTTP를 통해 게시된 에이전트에 메시지를 보내고 같은 응답에서 답변을 받을 수 있도록 n8n 에이전트에 새로운 webhook 채널을 추가했습니다. 이 엔드포인트는 OpenAI Responses API의 일부를 사용하므로, OpenAI SDK 클라이언트가 base URL을 에이전트 webhook URL로 설정하여 호출할 수 있습니다. 요청은 `input`을 문자열로, 선택적으로 `conversation`을 문자열 또는 `{ id }`로 보냅니다. 에이전트 메모리가 대화를 유지하므로 호출자는 새 메시지만 보내면 됩니다. 이 엔드포인트는 `model`을 무시하고, `stream: true`를 거부하며, 오류를 OpenAI 오류 형식(400, 401, 403, 404, 409, 500)으로 반환합니다. 작업은 각각 테스트를 통과하는 일곱 개의 커밋으로 나뉘었습니다. 먼저 작성자는 n8n Chat을 제외한 모든 채널이 자격 증명을 보유하고 Chat SDK 런타임을 실행한다는 공유 채널 가정을 두 개의 술어(`hasChannelRuntime`, `integrationNeedsCredential`)와 `acceptedCredentialTypes` 훅으로 대체했으며, 기존 채널 동작은 변경하지 않았습니다. 그다음 `webhook` 채널 유형과 설정(`authentication`: `none`, `headerAuth`, `jwtAuth`)을 추가했고, 설정이 없으면 초안 상태가 되며 복사/가져오기 시 설정이 제거됩니다. 다음으로 `N8N_AGENT_WEBHOOK_URL`과 `N8N_ENDPOINT_AGENT_WEBHOOK`, URL 서비스 메서드, 에디터용 REST 라우트가 추가되었습니다. 이 URL은 webhook URL로 대체되지 않는데, webhook 프로세스가 이 엔드포인트를 제공하지 않기 때문입니다. 그다음 단일 요청에 대해 게시된 에이전트를 실행하는 공개 라우트와 서비스가 추가되어, 대화를 확인하고, 같은 대화에서 두 번째 턴을 거부하며(409), 호출자 연결이 끊기면 실행을 중단하고, 도구 승인 시 500을 반환합니다. 알 수 없는 라우트와 잘못된 JSON도 OpenAI 오류 형식을 따르며, 엔드포인트 경로 설정은 다른 n8n 경로와의 충돌을 거부합니다. 이어서 Header 및 JWT 인증이 추가되어, 헤더 값을 상수 시간으로 비교하고 JWT는 자격 증명의 알고리즘과 PEM용 공개 키로만 검증합니다. 마지막으로 설정 스테퍼와 편집 뷰, 세션 필터 항목, 카탈로그 노출, 그리고 자격 증명이 없는 webhook 채널을 위한 MCP 도구 지원(`update_agent_integration`, `discover_agent_assets`)이 추가되었습니다. 작성자는 수동 테스트 경로를 문서화했습니다. 모델과 메모리를 켠 에이전트를 만들고, None 인증으로 Webhook 채널을 추가하고, 엔드포인트 URL을 복사하고, 게시한 다음, `conversation.id`를 다시 전달하며 두 개의 메시지를 curl로 보내는 것입니다. 또한 `/responses`가 없는 URL을 base URL로 사용하는 OpenAI SDK, 헤더 없이 403을 반환하고 헤더가 있으면 200을 반환하는 Header Auth, bearer 토큰 없이 401을 반환하고 잘못된 키, 잘못된 알고리즘, 또는 `alg: none`에 대해 403을 반환하는 JWT Auth, 그리고 `stream: true`(400), 알 수 없는 대화(404), 병렬 턴(409), 게시되지 않은 에이전트(404)에 대한 오류 검사를 보여주었습니다. 세션은 Webhook 출처로 필터링할 수 있으며, MCP 서버가 채널을 설정할 수 있습니다.

How it went

PR은 채널 구성, 엔드포인트, 인증 모드, 설정 UI, MCP 도구를 다루는 7개 커밋의 기능으로 머지되었으며, 각 커밋 후 테스트가 통과했습니다. 작성자는 curl과 OpenAI SDK로 오류 형태와 인증 실패를 포함한 동작을 수동으로 검증했습니다. 체크리스트 항목(docs, backport 레이블)은 게시물에서 체크되지 않은 채로 남아 있어, 문서 후속 작업과 릴리스 레이블링은 여전히 미결 상태였습니다.

Worth knowing

메인 인스턴스만 엔드포인트를 제공하며, URL은 webhook URL로 폴백되지 않습니다. 도구 승인은 나중에 이루어지기 때문에 500으로 턴을 종료합니다. Chat Completions 호환 엔드포인트는 없습니다. Chat Completions는 전체 메시지 목록을 전송하는 반면 이 채널은 대화를 에이전트 메모리에 유지하기 때문입니다. 에이전트의 복사본과 가져오기는 webhook 설정을 누락하므로, 복사본이 응답하려면 설정이 필요합니다. 에이전트가 대화를 유지하려면 메모리가 켜져 있어야 합니다. 설정 스텝퍼와 편집 화면의 스크린샷은 아직 추가되어야 했고, docs/backport 체크리스트 항목은 체크되지 않은 상태였습니다.

Wiring

환경에 `N8N_AGENT_WEBHOOK_URL`과 `N8N_ENDPOINT_AGENT_WEBHOOK`을 설정하세요. 엔드포인트는 main 인스턴스에서만 `{N8N_AGENT_WEBHOOK_URL}/{N8N_ENDPOINT_AGENT_WEBHOOK}/{agentId}/responses`로 제공됩니다. 에이전트 빌더에서 에이전트의 채널을 열고 Webhook을 추가한 뒤, 인증 방식(None, `httpHeaderAuth` credential을 사용하는 Header Auth, 또는 `jwtAuth` credential을 사용하는 JWT Auth)을 선택하고 엔드포인트 URL을 복사한 다음 게시하세요. 에이전트에는 모델과 메모리가 활성화되어 있어야 합니다. 호출자는 `input`과 선택적으로 `conversation`을 포함한 JSON을 POST합니다. OpenAI SDK의 경우 `baseURL`을 `/responses`를 제외한 URL로 설정하고 JWT를 `apiKey`로 전달하세요. REST 라우트는 편집기에 URL을 제공하며, MCP 서버는 `discover_agent_assets`(kind: integrations)와 `update_agent_integration`(type: webhook, settings: { authentication: 'none' })을 노출합니다.

Try it yourself

# Webhook 채널 추가 계획

## 개요

에이전트 플랫폼에 webhook 채널을 추가하여 외부 백엔드가 HTTP로 게시된 에이전트를 호출하고 같은 응답에서 답변을 받을 수 있도록 합니다. OpenAI Responses API의 부분집합을 사용합니다.

## API 계약

- `input`: 문자열 허용
- `conversation`: 문자열 또는 `{ id }` 허용 (선택)
- 대화 상태는 에이전트 메모리에 저장
- `model`은 무시
- `stream: true`는 400으로 거부
- 에러는 OpenAI 에러 형태로 반환 (400, 401, 403, 404, 409, 500)

## 인증 모드

1. **none** — 인증 없음
2. **Header Auth** — `httpHeaderAuth` credential 사용, 상수 시간 비교
3. **JWT Auth** — `jwtAuth` credential 사용, credential의 알고리즘만 검증하고 PEM에는 공개 키만 사용

## 엔드포인트

`{N8N_AGENT_WEBHOOK_URL}/{N8N_ENDPOINT_AGENT_WEBHOOK}/{agentId}/responses`

- main 인스턴스에서만 서빙
- webhook URL로의 폴백 없음

## 동작 규칙

- 같은 대화에서 두 번째 턴은 409로 거부
- 호출자가 연결을 끊으면 실행 중단
- 도구 승인 시 500 반환

## UI 작업

- 설정 스텝퍼 및 편집 뷰 추가
- 세션 필터 항목 추가
- credential 없이 webhook 채널을 연결하는 MCP 도구 지원

## 커밋 분할

각 커밋은 테스트가 통과하는 상태를 유지합니다.

1. **커밋 1** — webhook 채널 스키마 및 라우팅 골격, main 인스턴스 전용 서빙, 404/500 에러 형태
2. **커밋 2** — `input`/`conversation` 파싱, 에이전트 메모리 기반 대화 상태, `model` 무시, `stream: true` 400 거부
3. **커밋 3** — 인증 모드 (none, Header Auth 상수 시간 비교, JWT Auth 알고리즘/공개 키 검증) 및 401/403 에러
4. **커밋 4** — 같은 대화 두 번째 턴 409, 연결 끊김 시 실행 중단, 도구 승인 시 500
5. **커밋 5** — 설정 스텝퍼 및 편집 뷰, 세션 필터 항목
6. **커밋 6** — credential 없이 webhook 채널 연결을 위한 MCP 도구 지원

## 테스트

- 인증: none, Header Auth (일치/불일치, 상수 시간 비교), JWT Auth (알고리즘 검증, 공개 키 PEM)
- 에러 형태: 400, 401, 403, 404, 409, 500 각각의 OpenAI 에러 응답 구조
- 대화 처리: 문자열/`{ id }` conversation, 메모리 상태 유지, 두 번째 턴 409, 연결 끊김 시 중단