Issue Station
Sign In
Tools hereToolbox

openclaw - ✅(Solved) Fix [Bug]: Feishu(Lark) Webhook URL verification fails with 401 Invalid signature when encryptKey is set [2 pull requests, 2 comments, 3 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
openclaw/openclaw#58905•Fetched 2026-04-08 02:31:19
View on GitHub
Comments
2
Participants
3
Timeline
7
Reactions
0
Author
gaonicky2-droidgaonicky2-droid
Participants
11687841168784gaonicky2-droidgaonicky2-droidrnagulapallernagulapalle
Timeline (top)
commented ×2cross-referenced ×2labeled ×2referenced ×1

English: When configuring the Feishu (Lark) plugin in Webhook mode, there is a fundamental logic flaw in the authentication process that prevents developers from successfully verifying the Webhook URL in the Feishu Developer Console. 中文: 在配置 Feishu 频道的 Webhook 模式时，存在一个无法绕过的底层鉴权逻辑 Bug，导致开发者完全无法在飞书后台保存并验证 Webhook URL。

Error Message

Feishu UI throws an error: "返回数据不是合法的 JSON 格式" (Because it receives the 401 HTML error page). Once encryptKey is configured, OpenClaw indiscriminately intercepts all incoming requests missing the signature header, throwing a 401 Invalid signature error.

Root Cause

Set connectionMode: "webhook" in openclaw.json for the Feishu plugin. Provide valid appId, appSecret, verificationToken, and encryptKey. Start OpenClaw Gateway (starts successfully). Go to Feishu Developer Console -> Event Subscriptions. Enter the Gateway's public Webhook URL and click "Save". Feishu UI throws an error: "返回数据不是合法的 JSON 格式" (Because it receives the 401 HTML error page). Gateway logs show: feishu[default]: webhook anomaly path=/feishu/webhook status=401 count=1 Note: Verified via tcpdump that the raw POST request from Feishu's servers for the challenge verification indeed lacks the X-Lark-Signature header.

Fix Action

Fix / Workaround

Affected: Feishu channel users trying to use Webhook mode. Severity: Critical (completely blocks onboarding / setup of Feishu Webhook mode). Frequency: 100% reproducible on initial URL verification. Consequence: Developers cannot save their Webhook URL in the Feishu console, forcing them to modify source code or use Dispatcher mode.

Temporary workaround: Manually modify auth-profiles.js to bypass the signature check (e.g., return next() instead of throwing 401) during the initial Feishu setup, or switch to connectionMode: "dispatcher".

PR fix notes

PR #58938: Fix/feishu webhook url verification

Description (problem / solution / changelog)

Closes #58905

Summary

  • Problem: Feishu webhook mode rejects the initial url_verification request with 401 Invalid signature when encryptKey is configured.
  • Why it matters: Users cannot complete webhook URL verification in the Feishu developer console, so webhook mode is effectively blocked during setup.
  • What changed: Detect and respond to Feishu url_verification challenges before ordinary webhook signature auth, and add regression coverage for unsigned challenge requests.
  • What did NOT change: Signature validation for ordinary non-challenge webhook events is unchanged.

Root Cause

extensions/feishu/src/monitor.transport.ts validated x-lark-request-timestamp, x-lark-request-nonce, and x-lark-signature before checking whether the payload was a Feishu url_verification challenge.

When encryptKey is configured, isFeishuWebhookSignatureValid(...) returns false if those headers are missing, so the challenge path was unreachable and the handler always returned 401.

This diverged from the Lark SDK's challenge-first flow, where generateChallenge(...) is handled before normal event dispatch.

Changes

  • extensions/feishu/src/monitor.transport.ts

    • Parse the request body first
    • Detect Feishu url_verification challenges via Lark.generateChallenge(...)
    • Return the challenge response before ordinary webhook signature auth
    • Keep normal signature validation unchanged for non-challenge events

  • extensions/feishu/src/monitor.webhook-e2e.test.ts

    • Add coverage for unsigned plaintext url_verification requests
    • Add coverage for unsigned encrypted url_verification requests
    • Add a guard test that unsigned non-challenge events still return 401

Evidence & Repro

Before this change:

  • unsigned plaintext url_verification requests returned 401 Invalid signature
  • unsigned encrypted url_verification requests returned 401 Invalid signature
  • signed non-challenge events still worked

Expected:

  • url_verification returns {"challenge":"..."}
  • ordinary non-challenge events still require valid signature headers

Testing & Verification

Updated tests:

  • extensions/feishu/src/monitor.webhook-e2e.test.ts

Verified locally with:

pnpm test -- extensions/feishu/src/monitor.webhook-e2e.test.ts extensions/feishu/src/monitor.webhook-security.test.ts

Changed files

  • extensions/feishu/src/monitor.transport.ts (modified, +51/-7)
  • extensions/feishu/src/monitor.webhook-e2e.test.ts (modified, +65/-7)

PR #59990: fix(feishu): bypass signature check for encrypted URL verification challenges (#58905)

Description (problem / solution / changelog)

Summary

Feishu's initial webhook URL verification sends an encrypted body without X-Lark-Signature headers (per Feishu's official documentation). The strict signature gate rejected these requests with 401 before the challenge handler could run, creating an unresolvable deadlock that blocked webhook mode setup when encryptKey is configured.

Root Cause

In monitor.transport.ts, signature validation runs unconditionally before JSON parsing and challenge detection. When encryptKey is set, any request missing the signature headers is rejected with 401 — including Feishu's legitimate URL verification challenge that only carries an encrypted body.

Changes

  • extensions/feishu/src/monitor.transport.ts: Parse the webhook body early and handle encrypted challenge requests (body has encrypt field) before signature validation. The encryptKey decryption itself authenticates the sender — only a party that knows the encryptKey can produce a valid encrypted payload. Non-challenge requests and plaintext payloads still require full signature validation.
  • extensions/feishu/src/monitor.webhook-e2e.test.ts: Add e2e test for unsigned encrypted URL verification challenges.

Test

pnpm test -- extensions/feishu/src/monitor.webhook-e2e.test.ts
# 9 tests passed (8 existing + 1 new)

Closes #58905

Changed files

  • extensions/feishu/src/monitor.transport.ts (modified, +25/-2)
  • extensions/feishu/src/monitor.webhook-e2e.test.ts (modified, +34/-0)

Code Example

**Gateway Log snippet:**
`{"0":"{\"subsystem\":\"gateway/channels/feishu\"}","1":"feishu[default]: webhook anomaly path=/feishu/webhook status=401 count=1"}`

**Raw request captured via `tcpdump` from Feishu verification ping (Showing missing Signature headers):**

POST /feishu/webhook HTTP/1.0
Host: openclaw.autel.com:18789
X-Real-IP: 123.58.10.238
Connection: close
Content-Length: 206
User-Agent: Go-http-client/1.1
Content-Type: application/json;charset=utf-8

{"encrypt":"ddtFaQpGwQHD1l9rOsZRq9DSzLzFmoTTh86kdTll8C0a2XGQFKSUk/D3dcbQS77EBO/BuExNyCVgq8wc0QsaJz77qbT3C0nxgldxeVdd0AZxbKLBYmgmikdBN0oXOEYZKahC3LGuPDjYxogl4FUDrKFAu+F0UKbAUDtOKUJS9utwXyGb/rO/UtIUgF4DQuBa"}
RAW_BUFFERClick to expand / collapse

Bug type

Behavior bug (incorrect output/state without crash)

Beta release blocker

No

Summary

English: When configuring the Feishu (Lark) plugin in Webhook mode, there is a fundamental logic flaw in the authentication process that prevents developers from successfully verifying the Webhook URL in the Feishu Developer Console. 中文: 在配置 Feishu 频道的 Webhook 模式时，存在一个无法绕过的底层鉴权逻辑 Bug，导致开发者完全无法在飞书后台保存并验证 Webhook URL。

Steps to reproduce

Set connectionMode: "webhook" in openclaw.json for the Feishu plugin. Provide valid appId, appSecret, verificationToken, and encryptKey. Start OpenClaw Gateway (starts successfully). Go to Feishu Developer Console -> Event Subscriptions. Enter the Gateway's public Webhook URL and click "Save". Feishu UI throws an error: "返回数据不是合法的 JSON 格式" (Because it receives the 401 HTML error page). Gateway logs show: feishu[default]: webhook anomaly path=/feishu/webhook status=401 count=1 Note: Verified via tcpdump that the raw POST request from Feishu's servers for the challenge verification indeed lacks the X-Lark-Signature header.

Expected behavior

When OpenClaw receives an initial URL verification request containing the challenge field, it should bypass the strict header signature check (even if encryptKey is configured), decrypt the payload using the encryptKey, and return the {"challenge": "xxx"} response to complete the handshake.

Actual behavior

English: By capturing the raw request via tcpdump, we found that Feishu's official initial URL verification (Challenge) request sends an encrypted body, but does NOT include the X-Lark-Signature header (which is consistent with Feishu's official documentation for initial URL verification). However, OpenClaw has a logic deadlock: OpenClaw strictly requires encryptKey to be set in Webhook mode (if omitted, the plugin refuses to start and crashes). Once encryptKey is configured, OpenClaw indiscriminately intercepts all incoming requests missing the signature header, throwing a 401 Invalid signature error. This creates an inescapable deadlock: Feishu doesn't send the signature for the initial challenge request, but OpenClaw forcefully demands it and blocks the request. 中文: 通过 tcpdump 抓包飞书发往 Gateway 的底层请求发现： 飞书官方在进行首次 URL 验证（Challenge）时，发送的 POST 请求只包含加密的 Body，绝对不包含 X-Lark-Signature 等签名请求头（这符合飞书官方文档中关于 URL 验证的说明）。 然而，OpenClaw 代码存在死锁冲突： OpenClaw 强制 Webhook 模式必须配置 encryptKey（如果不配，插件直接报错拒绝启动）。 一旦配置了 encryptKey，OpenClaw 的底层逻辑就会无差别拦截所有不带签名 Header 的请求，直接抛出 401 Invalid signature。 这就导致飞书首次验证不发签名，OpenClaw 强要签名，形成解不开的死锁。

OpenClaw version

2026.03.28

Operating system

Ubuntu

Install method

No response

Model

openai-codex

Provider / routing chain

openclaw -> feishu plugin

Additional provider/model setup details

No response

Logs, screenshots, and evidence

**Gateway Log snippet:**
`{"0":"{\"subsystem\":\"gateway/channels/feishu\"}","1":"feishu[default]: webhook anomaly path=/feishu/webhook status=401 count=1"}`

**Raw request captured via `tcpdump` from Feishu verification ping (Showing missing Signature headers):**

POST /feishu/webhook HTTP/1.0
Host: openclaw.autel.com:18789
X-Real-IP: 123.58.10.238
Connection: close
Content-Length: 206
User-Agent: Go-http-client/1.1
Content-Type: application/json;charset=utf-8

{"encrypt":"ddtFaQpGwQHD1l9rOsZRq9DSzLzFmoTTh86kdTll8C0a2XGQFKSUk/D3dcbQS77EBO/BuExNyCVgq8wc0QsaJz77qbT3C0nxgldxeVdd0AZxbKLBYmgmikdBN0oXOEYZKahC3LGuPDjYxogl4FUDrKFAu+F0UKbAUDtOKUJS9utwXyGb/rO/UtIUgF4DQuBa"}

Impact and severity

Affected: Feishu channel users trying to use Webhook mode. Severity: Critical (completely blocks onboarding / setup of Feishu Webhook mode). Frequency: 100% reproducible on initial URL verification. Consequence: Developers cannot save their Webhook URL in the Feishu console, forcing them to modify source code or use Dispatcher mode.

Additional information

Temporary workaround: Manually modify auth-profiles.js to bypass the signature check (e.g., return next() instead of throwing 401) during the initial Feishu setup, or switch to connectionMode: "dispatcher".

extent analysis

TL;DR

The most likely fix is to modify the OpenClaw Feishu plugin to bypass the strict header signature check for the initial URL verification request.

Guidance

  • Identify the specific code path in the OpenClaw Feishu plugin that handles the initial URL verification request and modify it to bypass the signature check.
  • Verify that the modified code correctly handles the encrypted payload and returns the expected {"challenge": "xxx"} response.
  • Test the modified plugin with the Feishu Developer Console to ensure that the Webhook URL can be successfully verified and saved.
  • Consider adding a temporary workaround to the documentation, such as modifying the auth-profiles.js file or switching to connectionMode: "dispatcher", to help users who are affected by this issue.

Example

// Example code snippet to bypass signature check for initial URL verification
if (request.body.encrypt && !request.headers['X-Lark-Signature']) {
  // Bypass signature check for initial URL verification
  return next();
} else {
  // Perform normal signature check
  // ...
}

Notes

The provided code snippet is a hypothetical example and may not be the actual solution. The correct implementation will depend on the specific codebase and requirements of the OpenClaw Feishu plugin.

Recommendation

Apply a workaround by modifying the auth-profiles.js file to bypass the signature check during the initial Feishu setup, as this is a critical issue that completely blocks onboarding/setup of Feishu Webhook mode.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…

FAQ

Expected behavior

When OpenClaw receives an initial URL verification request containing the challenge field, it should bypass the strict header signature check (even if encryptKey is configured), decrypt the payload using the encryptKey, and return the {"challenge": "xxx"} response to complete the handshake.

#environment setup#docker error#permission error#memory optimization#batch processing

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING

openclaw - ✅(Solved) Fix [Bug]: Feishu(Lark) Webhook URL verification fails with 401 Invalid signature when encryptKey is set [2 pull requests, 2 comments, 3 participants]