Issue Station
Sign In
Tools hereToolbox

openclaw - ✅(Solved) Fix OpenClaw: add /hooks/message ingress with auth parity and clear hook boundaries [1 pull requests, 1 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#62526•Fetched 2026-04-08 03:03:00
View on GitHub
Comments
0
Participants
1
Timeline
2
Reactions
0
Author
vrknethavrknetha
Participants
vrknethavrknetha
Timeline (top)
cross-referenced ×1renamed ×1

Fix Action

Fix / Workaround

Processing behavior

  • kind=message
    • persist inbound user message to the active chat flow
    • emit chat final event path for active webchat sessions
    • trigger auto-reply dispatch
  • kind=event
    • operational webhook event behavior only
    • no auto-reply dispatch

PR fix notes

PR #62528: Gateway: add /hooks/message ingress with webhook auth parity

Description (problem / solution / changelog)

Summary

Adds a generic webhook ingress endpoint at POST /hooks/message with auth + safety parity to existing webhook routes, and enforces single-responsibility boundaries between /hooks/agent and /hooks/message.

Closes #62526.

Single-Responsibility Boundary

  • /hooks/agent is now automation-only (run isolated agent task) and no longer mirrors run summaries/errors into main-session system events.
  • Shared delivery-contract runs no longer enqueue main-session awareness mirrors in cron delivery dispatch.
  • /hooks/message remains the inbound transport path for chat visibility + optional auto-reply.

Auth Parity Checklist

  • Accepts token from Authorization: Bearer and X-OpenClaw-Token
  • Rejects query token usage (?token=...) with 400
  • Reuses shared constant-time secret compare path
  • Reuses shared auth failure limiter bucket + client IP normalization
  • Returns 401 on missing/invalid token
  • Returns 429 on repeated auth failures

Request Safety Parity Checklist

  • POST only (405 for non-POST)
  • Reuses existing body size and timeout guards
  • Reuses existing idempotency extraction and replay cache
  • Retries dedupe for /hooks/message via idempotency key, with requestId fallback when header is absent

Webhook Contract (/hooks/message)

Required fields:

  • message: string
  • requestId: string

Optional fields:

  • kind: "message" | "event" (defaults to "message")
  • sessionKey
  • source
  • sender
  • conversation
  • metadata

Behavior:

  • kind="message": dispatches through chat send path, emits chat final event path, triggers auto-reply dispatch
  • kind="event": records operational event path without auto-reply dispatch

Logging

Adds deterministic lifecycle logs for ingress:

  • hook.message.received
  • hook.message.persisted
  • hook.message.reply.started
  • hook.message.reply.completed
  • hook.message.failed

Each log line includes:

  • requestId, sessionKey, kind, source, senderId, conversationId, groupId, status

Test Evidence

Executed:

  • pnpm test src/gateway/server.hooks.test.ts src/gateway/server-http.hooks-request-timeout.test.ts src/cron/isolated-agent/delivery-dispatch.double-announce.test.ts
    • Result: gateway suites 2 passed / 28 tests, cron delivery suite 1 passed / 32 tests
  • pnpm test src/cron/isolated-agent/run.message-tool-policy.test.ts
    • Result: 1 passed / 5 tests

Coverage in updated tests includes:

  • auth parity (401, 429, valid auth headers, query-token rejection)
  • safety parity (405, request guard behavior, dedupe retry semantics)
  • message behavior (kind=message triggers dispatch and chat final path, kind=event avoids auto-reply dispatch)
  • /hooks/agent no automatic main-session mirror side effects
  • shared delivery-contract no awareness mirroring in cron dispatch
  • UI validation (active webchat receives chat final update for webhook message flow)

Notes

  • pnpm check currently fails on unrelated pre-existing type errors in provider artifact surfaces outside this diff; targeted gateway/cron suites above are green.

Changed files

  • docs/automation/cron-jobs.md (modified, +29/-1)
  • docs/gateway/configuration-reference.md (modified, +4/-0)
  • docs/gateway/configuration.md (modified, +1/-0)
  • src/cron/AGENTS.md (added, +26/-0)
  • src/cron/isolated-agent/delivery-dispatch.double-announce.test.ts (modified, +19/-0)
  • src/cron/isolated-agent/delivery-dispatch.ts (modified, +20/-4)
  • src/cron/isolated-agent/run.ts (modified, +2/-1)
  • src/gateway/AGENTS.md (added, +35/-0)
  • src/gateway/hooks.ts (modified, +93/-0)
  • src/gateway/server-http.hooks-request-timeout.test.ts (modified, +73/-0)
  • src/gateway/server-http.test-harness.ts (modified, +3/-0)
  • src/gateway/server-http.ts (modified, +176/-7)
  • src/gateway/server-runtime-state.ts (modified, +3/-0)
  • src/gateway/server.hooks.test.ts (modified, +421/-26)
  • src/gateway/server.impl.ts (modified, +5/-1)
  • src/gateway/server/hooks.ts (modified, +389/-26)
  • src/gateway/test-helpers.runtime-state.ts (modified, +2/-3)
RAW_BUFFERClick to expand / collapse

Scope

Add a generic POST /hooks/message ingress endpoint with auth and request-safety parity to existing hook routes, and enforce clear responsibilities between /hooks/agent and /hooks/message.

Problem

OpenClaw supports webhook wake/agent entrypoints, but there is no generic webhook message ingress route that can inject inbound user text into gateway chat flows while preserving existing webhook security and safety controls.

Also, /hooks/agent has been interpreted as both automation execution and chat-visibility mirroring, which mixes responsibilities.

Proposal

Add POST {hooks.path}/message and reuse existing hook pipeline behavior without route-specific auth or body-reader logic.

Auth parity requirements

  • Accept token from Authorization: Bearer <token> or X-OpenClaw-Token
  • Reject token-in-query usage
  • Reuse existing constant-time secret comparison
  • Reuse existing auth failure rate-limit bucket and client IP handling

Request safety parity requirements

  • POST only
  • Same body size limit and timeout behavior as current hook routes
  • Same idempotency extraction and replay cache behavior

Generic payload contract

Required:

  • message (string)
  • requestId (string)

Optional:

  • kind (message|event)
  • sessionKey
  • source
  • sender
  • conversation
  • metadata

Processing behavior

  • kind=message
    • persist inbound user message to the active chat flow
    • emit chat final event path for active webchat sessions
    • trigger auto-reply dispatch
  • kind=event
    • operational webhook event behavior only
    • no auto-reply dispatch

Responsibility boundary

  • /hooks/agent is automation execution only:
    • schedule/execute isolated run
    • return run metadata (runId, status)
    • no implicit main-session/chat UI mirroring fallback
  • /hooks/message is the inbound transport path for chat visibility:
    • ingress + persistence + broadcast (and optional auto-reply)
  • delivered semantics for /hooks/agent runs:
    • reflects delivery-route/tool completion
    • does not imply extra chat UI mirroring side effects

Logging

Add deterministic ingress lifecycle logs:

  • hook.message.received
  • hook.message.persisted
  • hook.message.reply.started
  • hook.message.reply.completed
  • hook.message.failed

Log fields:

  • requestId
  • sessionKey
  • kind
  • source
  • senderId
  • conversationId
  • groupId
  • status

Acceptance

  • Auth parity for /hooks/message (401, 429, valid header auth, query-token rejection)
  • Request guard parity (405, body guard behavior, idempotent retry dedupe)
  • Kind behavior (message triggers auto-reply path, event does not)
  • Active chat session receives webhook-driven updates via chat event path (history fallback when available)
  • /hooks/agent has no automatic main-session mirror side effects
  • Shared-delivery hook-agent runs do not enqueue awareness/system-event mirrors as chat-visibility fallback

extent analysis

TL;DR

Implement a new POST /hooks/message endpoint with auth and request-safety parity to existing hook routes, and enforce clear responsibilities between /hooks/agent and /hooks/message.

Guidance

  • Implement the POST /hooks/message endpoint with the required authentication and request safety features, including token-based auth, rate limiting, and body size limits.
  • Define a clear payload contract for the endpoint, including required fields (message and requestId) and optional fields (kind, sessionKey, source, sender, conversation, and metadata).
  • Implement processing behavior for kind=message and kind=event payloads, including persisting inbound user messages, emitting chat final events, and triggering auto-reply dispatch.
  • Update logging to include deterministic ingress lifecycle logs with relevant fields (e.g., requestId, sessionKey, kind, source, senderId, conversationId, groupId, and status).

Example

POST /hooks/message HTTP/1.1
Authorization: Bearer <token>
Content-Type: application/json

{
  "message": "Hello, world!",
  "requestId": "12345",
  "kind": "message",
  "sessionKey": "abc123",
  "source": "webchat",
  "sender": "John Doe",
  "conversation": "12345",
  "metadata": {}
}

Notes

The implementation should ensure that the new endpoint has auth and request-safety parity with existing hook routes, and that the responsibilities between /hooks/agent and /hooks/message are clearly defined and enforced.

Recommendation

Apply the proposed changes to implement the POST /hooks/message endpoint with the required features and behaviors, as this will provide a generic webhook message ingress route that can inject inbound user text into gateway chat flows while preserving existing webhook security and safety controls.

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…
#indexing error#inference speed#output truncation#response parsing#generation error

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 OpenClaw: add /hooks/message ingress with auth parity and clear hook boundaries [1 pull requests, 1 participants]