Skip to content

docs(webhook): address review feedback for #55830 #10

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
yungchentang wants to merge 1 commit into
base: liuhao/cron-bugfix-55829-webhook-raw-truncate
Choose a base branch
from
Open

docs(webhook): address review feedback for #55830 #10

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 5 additions & 5 deletions website/docs/user-guide/messaging/webhooks.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -125,17 +125,17 @@ Prompts use dot-notation to access nested fields in the webhook payload:

- `{pull_request.title}` resolves to `payload["pull_request"]["title"]`
- `{repository.full_name}` resolves to `payload["repository"]["full_name"]`
- `{__raw__}` — special token that dumps the **entire payload** as indented JSON (truncated at 4000 characters). Useful for monitoring alerts or generic webhooks where the agent needs the full context.
- `{__raw__}` — special token that dumps the **entire payload** as indented JSON. The bare form is truncated at 4000 characters; use `{__raw__:N}` (for example, `{__raw__:20000}`) to set a per-use character limit.
- Missing keys are left as the literal `{key}` string (no error)
- Nested dicts and lists are JSON-serialized and truncated at 2000 characters

You can mix `{__raw__}` with regular template variables:
You can mix either raw-payload form with regular template variables:

```yaml
prompt: "PR #{pull_request.number} by {pull_request.user.login}: {__raw__}"
prompt: "PR #{pull_request.number} by {pull_request.user.login}: {__raw__:20000}"
```

If no `prompt` template is configured for a route, the entire payload is dumped as indented JSON (truncated at 4000 characters).
If no `prompt` template is configured for a route, the entire payload is dumped as indented JSON with the unchanged 4000-character limit. The `{__raw__:N}` override applies only inside a configured template.

The same dot-notation templates work in `deliver_extra` values.

Expand Down Expand Up @@ -322,7 +322,7 @@ hermes webhook subscribe antenna-matches \

- `deliver_only: true` requires `deliver` to be a real target. `deliver: log` (or omitting `deliver`) is rejected at startup — the adapter refuses to start if it finds a misconfigured route.
- The `skills` field is ignored in direct delivery mode (no agent runs, so there's nothing to inject skills into).
- Template rendering uses the same `{dot.notation}` syntax as agent mode, including the `{__raw__}` token.
- Template rendering uses the same `{dot.notation}` syntax as agent mode, including `{__raw__}` with its 4000-character default and `{__raw__:N}` for a per-use limit.
- Idempotency uses the same `X-GitHub-Delivery` / `X-Request-ID` header — retries with the same ID return `status=duplicate` and do NOT re-deliver.

---
Expand Down
12 changes: 6 additions & 6 deletions ...zh-Hans/docusaurus-plugin-content-docs/current/user-guide/messaging/webhooks.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -125,17 +125,17 @@ Prompt 使用点号表示法访问 webhook payload 中的嵌套字段：

- `{pull_request.title}` 解析为 `payload["pull_request"]["title"]`
- `{repository.full_name}` 解析为 `payload["repository"]["full_name"]`
- `{__raw__}` — 特殊 token，将**整个 payload** 以缩进 JSON 格式转储（截断至 4000 个字符）。适用于监控告警或通用 webhook，agent 需要完整上下文时使用。
- `{__raw__}` — 特殊 token，将**整个 payload** 以缩进 JSON 格式转储。裸写形式默认截断至 4000 个字符；使用 `{__raw__:N}`（例如 `{__raw__:20000}`）可为单次使用设置字符上限。
- 缺失的键保留为字面量 `{key}` 字符串（不报错）
- 嵌套的 dict 和 list 会被 JSON 序列化并截断至 2000 个字符

可以将 `{__raw__}` 与常规模板变量混合使用：
可以将任一 raw payload 形式与常规模板变量混合使用：

```yaml
prompt: "PR #{pull_request.number} by {pull_request.user.login}: {__raw__}"
prompt: "PR #{pull_request.number} by {pull_request.user.login}: {__raw__:20000}"
```

若路由未配置 `prompt` 模板，则将整个 payload 以缩进 JSON 格式转储（截断至 4000 个字符）。
若路由未配置 `prompt` 模板，则整个 payload 仍以缩进 JSON 格式转储，并保持 4000 个字符的默认上限。`{__raw__:N}` 覆盖只适用于已配置的模板。

`deliver_extra` 的值中同样支持点号表示法模板。

Expand Down Expand Up @@ -322,7 +322,7 @@ hermes webhook subscribe antenna-matches \

- `deliver_only: true` 要求 `deliver` 为真实目标。`deliver: log`（或省略 `deliver`）在启动时会被拒绝——适配器发现路由配置错误时拒绝启动。
- 直接投递模式下 `skills` 字段被忽略（不运行 agent，无处注入 skill）。
- 模板渲染使用与 agent 模式相同的 `{dot.notation}` 语法，包括 `{__raw__}` token。
- 模板渲染使用与 agent 模式相同的 `{dot.notation}` 语法，包括默认上限为 4000 个字符的 `{__raw__}`，以及可设置单次上限的 `{__raw__:N}`。
- 幂等性使用相同的 `X-GitHub-Delivery` / `X-Request-ID` 请求头——携带相同 ID 的重试返回 `status=duplicate` 且**不**重复投递。

---
Expand Down Expand Up @@ -481,4 +481,4 @@ Webhook payload 包含攻击者可控的数据——PR 标题、commit 消息、
|----------|-------------|---------|
| `WEBHOOK_ENABLED` | 启用 webhook 平台适配器 | `false` |
| `WEBHOOK_PORT` | 接收 webhook 的 HTTP 服务器端口 | `8644` |
| `WEBHOOK_SECRET` | 全局 HMAC secret（路由未指定自身 secret 时作为回退） | _（无）_ |
| `WEBHOOK_SECRET` | 全局 HMAC secret（路由未指定自身 secret 时作为回退） | _（无）_ |