webhook-dx-audit

Webhook 体验审计

端到端审计平台客户对其出站 Webhook 和事件目标的体验，从发现到投入生产，并生成一份带有具体、按优先级排列的建议的评分 YAML 审计文件。

审计对象可以是任何向开发者发送事件的公司（Stripe、Shopify、Paddle 或规模较小的平台）。评估集成开发者实际会遇到的内容：文档、控制面板、签名、重试、可观测性和工具，仅使用公开可查或产品中已开放的信息。

范围：Webhook 和事件目标。 将“出站 Webhook”和“事件目标”视为同一项审计。行业术语尚在演变：Stripe 推广了“事件目标”（现在除 Webhook 外，还可直接向 Amazon EventBridge 和 Azure Event Grid 投递事件）；Shopify 提供 HTTP Webhook、EventBridge 和 Pub/Sub 目标，并正在推广“事件订阅”这一品牌；其他平台仍将整个领域称为“Webhook”。现代服务应包含哪些功能，可参考 https://eventdestinations.org 上的 Event Destinations 计划。无论平台选择何种名称，都应按照这一更广义的概念评分。对于仅支持 Webhook 的平台，针对其他目标类型的标准应标记为“不适用”（第 6 类别中的目标类型广度标准仍计 0 分，因为确实存在覆盖范围不足）。

三种状态，两种分数。 每项标准最终为 0/1/2 分、“不支持”（= 0，且标注意图）、“不适用”（逻辑上不适用，不计入计算），或“未评估”（无法触达，例如第 1 轮审计中需要登录控制面板才能查看）。第 1 轮会基于同一组数据计算两个汇总结果：公开范围评级（当前可触达的内容）和暂定最低评级（如果始终不进行人工介入（HITL）验证时的最低评级）。定义见 references/rubric.md，计算方法见 references/scoring.md。

受众很重要。 在审计开始时声明平台的目标受众：developer-platform（集成者是软件工程师）、no-code-saas（集成者是通过 UI 配置自动化流程的高级用户）或 mixed（受众不止一种，且 Webhook 功能面服务于特定层级）。访问平台主页并引用具体信号（首屏文案、导航结构、客户评价、定价层级、API 的突出程度）来验证该分类；检查清单见 references/methodology.md 的第 0 步。rubric.md 中由受众决定的 N/A 逻辑会排除不适用的标准（例如，纯无代码 SaaS 的 IaC 和本地开发工作流模拟标准为 N/A；对于 mixed，应根据判断逐项评分）。仅当无法访问主页时，才将 developer-platform 作为第 1 轮的后备分类；第 2 轮必须通过 HITL 验证重新检查。

视角：人类开发者的体验。 第 1 至第 11 类评估的是集成平台时用户会遇到的内容，因此要像人一样阅读文档：开发者访问的渲染后 HTML 页面，而不是 .md 或 llms.txt 导出文件。是否提供这些机器可读文档格式，是仅在第 12 类中评分的 AI 就绪度信号。所有 AI 和 Agent 评估都应限定在第 12 类；不得将其延伸到其他十一类。（为第 4 类获取 OpenAPI 等正式 API/事件规范没有问题，因为这服务于面向人的代码生成和验证，与用机器文档导出文件替代面向人的文档不同。）

可以获取页面的 .md 导出文件，以提取引文或加快证据收集；但规则是：评分依据必须是渲染后的 HTML 页面呈现给人类的内容，而不是 .md 文件中的内容。如果两者不一致，应将其视为证据缺口，而不能自行选择更有利的一方。

适用场景

凡是需要评审、评分或评价某个平台的 Webhook 或事件目的地开发者体验（DX）的请求，都适用本流程。评审范围涵盖从开始接入到首次成功投递 Webhook、本地开发体验、本地到生产环境的迁移、事件类型、Webhook 签名、重试支持及示例。如需了解评审发现与 Hookdeck 相关产品的对应关系，请参阅 references/program-mapping.md。

角色分工

这是一项协作任务。大部分工作由你（Agent）完成，但有些证据需要登录，或只能通过人类才能访问的界面获取。请据此划分工作，不要为了等待人类而搁置本可以先行完成的工作。

**你（Agent）负责无需人工参与、通过公开渠道完成的工作：**实现指南、事件目录和架构、安全与身份验证（根据文档）、投递语义（根据文档）、SDK 和验证（阅读实际仓库源码，而不只是 README）、API/CLI/IaC 设置入口（文档、Terraform Registry），以及 Agent/AI 就绪情况（llms.txt、hookdeck/webhook-skills 仓库及任何 MCP）。此外，所有评分计算和 YAML 审计报告也由你负责。这是审计工作的大部分内容。

**必须由人类完成的工作：**创建账户（注册几乎总是需要人工完成电子邮件确认、验证码或添加银行卡），以及无法仅凭文档评估的产品内功能：配置仪表板、触发测试事件并确认其成功送达、面向消费者的投递日志，以及自助式终端节点/订阅管理。

**关键的人机协作（HITL）证据：示例投递载荷。**人类每次触发测试事件或查看真实投递时，都要捕获完整的投递载荷（所有请求标头和请求正文），并分享给审计人员。实际投递往往会揭示文档未说明的信息：当前使用的签名模式、实际使用的去重 ID 标头名称、时间戳格式、运营者是否在目的地设置了自定义标头，以及发送方的 User-Agent 标识。拿到可用于评分的载荷后，审计人员就能建议“说明你们已在发送的 webhook-signature 标头”，而不是较为笼统地建议“添加签名方案”。如果没有载荷，建议就只能是有条件的（“在默认模式下，标头是 X；在 Standard Webhooks 模式下则是 Y”），集成者还得自行判断适用哪种情况。

**HITL 捕获内容应填入结构化字段，而不是叙述性段落。**投递载荷应写入 audit.hitl_evidence.delivery_payload_capture，作为结构化对象（包含 signing_mode、headers 映射、body、custom_headers_feature_in_use 和示例值）。产品内观察结果应写入 audit.findings[].criteria[].evidence 字符串，并以标准 id 为键（即为该观察结果评分的标准）；如果观察结果由受众决定或专属 HITL，还应将其记录在 audit.hitl_evidence.scoring_decisions 或 audit.hitl_evidence.other_observations 中。不要在 summary 字段中写入“第二轮 HITL 将等级从 F 提升到了 D……”这类自由叙述；双重评分数据已记录在 grade.public_scope 和 grade.provisional_minimum 中，第二轮审计已完成的标准则记录在 passes.pass_2.closed_criteria 中。摘要应描述平台的 Webhook 开发者体验，而不是审计流程本身。

人类可通过以下任一方式处理需要权限的部分，任选其一：

• **转述：**人类点击查看相关内容，并将截图或几句观察结果发回，你据此评分。
• **经过身份验证的浏览器：**人类登录并将会话交给你（Claude in Chrome），由你在其监督下自行浏览仪表板。注册本身通常仍需人类完成。

如果人类没有指定方式，默认采用转述。切勿为了避免询问而臆测需要权限的功能；应将其标记为“未评估”（或在符合逻辑规则时标记为“不适用”），并交由人类处理。

审计流程

分两轮执行，让人工介入时间尽可能短，并提出明确的问题。每轮的输出都是审计 YAML 文件（基于 assets/report-template.yaml 搭建）；中间不生成 Markdown。

0. 搭建审计 YAML。 将 assets/report-template.yaml 复制到调用方指定的路径。填写 audit.platform、audit.prepared 和 audit.reviewer 块。默认流程为：第 1 轮无人值守，第 2 轮由 Agent 发起 HITL 提问（在第 2 轮收集 HITL 证据；步骤 4 会写入同级目录下的 hitl-evidence.yaml，以便重新审计时跳过这些问题）。

   预加载例外。 如果同级目录下已有 hitl-evidence.yaml（之前运行的输出，或从早期审计中保留并手动移植的记录），现在读取它，并将记录复制到 audit.hitl_evidence。对于预加载记录已回答的任何标准，跳过第 2 轮的问题。这是例外情况；大多数新审计都没有预加载证据。

1. 确认范围和输入。 获取平台名称及其文档 URL。询问人工是否能提供测试账号（以及偏好的介入模式）。如果未说明，默认仅使用公开信息，采用中继模式。

2. 第 1 轮，无人值守研究。 遵循 references/methodology.md。按以下顺序检查公开信息：开发者实际阅读的渲染后 HTML 文档（而非 .md/llms.txt 导出文件）、用于事件架构标准的机器可读规范（OpenAPI / AsyncAPI / JSON Schema）、文档记录的注册/入门流程、通过 API 配置 webhook、签名与验证、重试和投递行为、SDK、CLI/IaC，以及文档记录的本地开发方案。为每项结论记录来源链接或产品内参考。边研究边填写 audit.findings 和 audit.sources；对于能够根据公开证据得出结论的标准，拟定评分。不要推断没有证据支持的功能。

3. 向人工提供核对清单。 仅列出你无法确认、需要人工在产品内执行或观察的事项，清单应简短具体，并说明要执行的操作以及需要反馈的内容（例如：“触发一个测试事件，并告知我事件是否送达、是否带有签名”；“打开投递日志，确认能否看到响应正文和状态”；“捕获并粘贴一次真实投递的完整请求载荷，包括所有标头和正文，以便我在建议中指出实际的签名标头、去重 ID 和任何自定义标头”）。如果使用经过身份验证的浏览器模式，待人工登录后由你自行操作，不要将任务交给人工。如果本次按设计仅执行第 1 轮（不计划第 2 轮），则跳过核对清单，将受限标准标记为 Not Assessed，并为每项填写一行理由，然后继续步骤 4。双评分等级（audit.grade.public_scope 和 audit.grade.provisional_minimum）会显示哪些内容可查证、哪些不可查证。

4. 第 2 轮，完成评分并保存 HITL 证据。 将人工的观察结果（或你在浏览器中看到的内容）纳入剩余标准。阅读 references/rubric.md；根据三状态分类法，为每项标准评分 0/1/2、Not Supported（= 0，且需标注意图）、Not Applicable 或 Not Assessed。将已提供的投递载荷记录到 audit.hitl_evidence.delivery_payload_capture；产品内观察记录为 audit.findings[].criteria[].evidence 字符串。由受众驱动或特定于 HITL 的评分决策，记录到 audit.hitl_evidence.scoring_decisions 中。将第 2 轮使其脱离 Not Assessed 状态的标准 ID 更新到 audit.passes.pass_2.closed_criteria。纳入 HITL 信息后，Not Assessed 标准应很少或不再存在；公开范围评分和临时最低评分将趋于一致，此时可以从 audit.grade 中删除双评分子对象。 首次为某个平台收集 HITL 证据时，务必同时编写同级的 hitl-evidence.yaml 配套文件，以便未来重新审计时预加载该文件，跳过相关询问。路径模式与审计文件相同：如果审计文件是 foo/bar/audit.yaml，配套文件就是 foo/bar/hitl-evidence.yaml。该配套文件须符合 schema/hitl-evidence.schema.yaml（顶层为 hitl_evidence:，且必须包含 platform 字段）。如果步骤 0 已预加载配套文件，则将 Pass 2 中新观察到的内容更新到该文件中。

5. 计算等级。 按照 references/scoring.md 将各项标准的得分汇总为加权类别得分、总百分比和等级区间。填写 audit.scorecard[].score_pct、audit.grade.overall_pct、audit.grade.band 和 audit.grade.coverage。

6. 撰写摘要和建议。 audit.summary 是唯一需要撰写的大段文字：简要描述该平台的 webhook DX、主要等级，以及一两项最重要的内容，面向开发者交流。运用 references/methodology.md 中的“将摘要限定于 webhook 表层功能”和“保持客观，不作评论”方法。audit.recommendations 是按影响 x 易行度排序的优先事项列表；对于每个实质性差距，在相关时指出 references/program-mapping.md 中对应的 Hookdeck 产品，但要将其表述为可选方案，而非强制要求。每条建议都要包含 why（对集成方的益处，与 body 中的修改描述分开）。对于每条用于弥补评分差距的建议，都要填写 target_scores（该建议能将哪些标准提升到 0/1/2）、depends_on（对其他建议 ID 的硬性依赖）和 effort（docs | s | m | l）；这些字段用于下游的当前与潜在评分卡，以及每条建议的工作量和依赖关系展示。校准方法请参阅 references/methodology.md 中的“撰写建议”和“填写 target_scores、depends_on、effort”。当至少一条建议包含 target_scores 时，按照方法中的投影规则计算 grade.projected 和各类别的 scorecard[].projected_pct。交付前运行 npm run lint:file -- <path> 检查结果。请预期人工会进行审阅和修正；他们往往掌握你无法看到的背景信息。

证据规范

这份审计的价值在于有据可依且具体。以下规则有助于保持其严谨性：

• 区分观察到的内容与推断的内容。如果文档声称某种行为，但你无法测试，应写“文档记载”，而不是“已验证”。
• 引用或链接每项发现所依据的具体文档页面、API 字段或控制面板界面。没有来源的发现只是猜测。
• 访问受限时，优先使用“似乎”“文档记载为”和“无法确认”，避免下定论。
• 谨慎说明缺失情况：“没有关于 X 的公开文档”是合理的；“X 不存在”通常不妥，除非你已确认这一点。

输出

一份符合 schema/audit.schema.yaml 的结构化 YAML 审计文件。其结构包括：

• 标头字段（platform、prepared、access、audience、reviewer、passes）；
• grade，包含 overall_pct、band、可选的双重评分详情（public_scope、provisional_minimum、hitl_headroom_pct）和 coverage 计数；
• summary（多行块标量，是审计中唯一的大段文字）；
• scorecard（按评分标准顺序排列的每个类别对应一项）；
• findings（每个类别一项，包含各项标准的详情、证据、状态和交叉引用）；
• recommendations（按影响 x 易行度排序的优先事项列表）；
• 可选的嵌入式 hitl_evidence（交付负载捕获及基于 HITL 的评分决策）；
• access_limits 和 sources。

保持面向开发者交流的语气：具体、不使用营销语言、不夸大。使用美式英语。下游使用 YAML 的组件（客户报告技能、云端 Agent 的渲染器、CLI 查看器）会负责呈现。

参考文件

• references/rubric.md：列出 12 个评分类别及其所有评估标准，包含 0/1/2 分锚点和考察要点。评分前请先阅读。
• references/methodology.md：介绍如何通过公开信息为各类别寻找证据，以及适用于审计文本字段的写作技巧。收集信息前请先阅读。
• references/scoring.md：介绍类别权重、计算方法和等级区间。评级前请先阅读。
• references/program-mapping.md：将差距领域映射到对应的 Hookdeck 产品，以用于建议部分。
• schema/audit.schema.yaml：以 YAML 编写的 JSON Schema（Draft 2020-12）。这是审计结构、固定的 CategoryId 和 CriterionId 枚举，以及保留的云端 Agent 字段的权威来源。
• schema/README.md：介绍状态分类体系、双评分处理方式，以及如何运行检查器。
• assets/report-template.yaml：需要填写的确切输出结构。请以此文件为模板搭建审计 YAML。