From 2dcb684e94c26b560f85c37f4c0f96e779532f64 Mon Sep 17 00:00:00 2001
From: RhenCloud <i@rhen.cloud>
Date: Mon, 3 Aug 2026 09:51:40 +0800
Subject: [PATCH] docs: document workflow_run in-place message updates

---
 docs/events/supported.md    | 6 +++++-
 docs/zh/events/supported.md | 6 +++++-
 2 files changed, 10 insertions(+), 2 deletions(-)

diff --git a/docs/events/supported.md b/docs/events/supported.md
index c949245..569ce3a 100644
--- a/docs/events/supported.md
+++ b/docs/events/supported.md
@@ -10,7 +10,7 @@ WebHooker supports 23 GitHub webhook event types, each with a dedicated formatte
 | `pull_request`                | PR opened/closed/merged/edited | PR title, branch, diff stats, labels             |
 | `issues`                      | Issue opened/closed/edited     | Issue title, labels, assignees                   |
 | `issue_comment`               | Comment on issue or PR         | Comment body, issue reference                    |
-| `workflow_run`                | CI/CD workflow completed       | Workflow status, conclusion, duration            |
+| `workflow_run`                | CI/CD workflow phase updated   | Workflow status, conclusion, duration; phases update a single message in place |
 | `release`                     | Release published/edited       | Tag, body, assets, pre-release flag              |
 | `create`                      | Branch or tag created          | Ref name, ref type                               |
 | `delete`                      | Branch or tag deleted          | Ref name, ref type                               |
@@ -55,6 +55,10 @@ Any event type without a dedicated formatter falls through to the generic format
 - Repository name
 - Raw payload as code block (truncated to 1000 chars)
 
+## In-Place Message Updates
+
+`workflow_run` events (queued → running → success/failure) are sent once and then **edited in place** for each subsequent phase instead of posting a new message. The original message's link preview, author, and field layout are preserved; only the status, conclusion emoji, duration, and title are refreshed. Supported on both Discord (`editMessage`) and Telegram (`editMessageText` / `editMessageCaption`).
+
 ## Filter Compatibility
 
 See the [Filter Tutorial](../guide/filters) for a hands-on guide with worked examples.
diff --git a/docs/zh/events/supported.md b/docs/zh/events/supported.md
index d973a1f..6f92f5e 100644
--- a/docs/zh/events/supported.md
+++ b/docs/zh/events/supported.md
@@ -10,7 +10,7 @@ WebHooker 支持 23 种 GitHub webhook 事件类型，每种都有专用的格
 | `pull_request`                | PR 打开/关闭/合并/编辑 | PR 标题、分支、差异统计、标签          |
 | `issues`                      | 议题打开/关闭/编辑     | 议题标题、标签、指派人                 |
 | `issue_comment`               | 议题或 PR 的评论       | 评论内容、议题引用                     |
-| `workflow_run`                | CI/CD 工作流完成       | 工作流状态、结论、耗时                 |
+| `workflow_run`                | CI/CD 工作流阶段更新   | 工作流状态、结论、耗时；各阶段原地更新同一条消息 |
 | `release`                     | 发布创建/编辑          | 标签、内容、附件、预发布标记           |
 | `create`                      | 分支或标签已创建       | 引用名称、引用类型                     |
 | `delete`                      | 分支或标签已删除       | 引用名称、引用类型                     |
@@ -55,6 +55,10 @@ WebHooker 支持 23 种 GitHub webhook 事件类型，每种都有专用的格
 - 仓库名称
 - 原始载荷作为代码块（截断到 1000 字符）
 
+## 原地消息更新
+
+`workflow_run` 事件（queued → running → success/failure）只发送一条消息，后续每个阶段会**原地编辑**该消息，而不是发送新消息。消息的链接预览、作者和字段布局保持不变，仅刷新状态、结论 emoji、耗时和标题。Discord（`editMessage`）和 Telegram（`editMessageText` / `editMessageCaption`）均支持。
+
 ## 过滤器兼容性
 
 实操指南见[过滤器教程](../guide/filters)，包含完整示例。