enonic-webhook-integrator

Enonic Webhook 集成器

流程

步骤 1：检测 Enonic XP 项目

1. 执行 node scripts/find-enonic-targets.mjs .，在工作区中查找 Enonic XP 项目根目录。
2. 如果脚本返回空数组，请停止并说明未找到 Enonic XP 项目。
3. 如果找到多个项目，请询问应在哪个项目中进行集成。
4. 从 gradle.properties（appName）或 build.gradle 中识别应用程序键。

步骤 2：确定集成方向

1. 将任务归类为以下类型之一：出站事件监听器（XP 响应内部事件并调用外部系统）、出站 Webhook 配置（XP 通过内置配置发送 Webhook 负载）、入站 Webhook 端点（XP 接收来自外部系统的负载），或混合（以上类型的组合）。
2. 阅读 references/event-reference.md，确定正确的事件类型、监听器模式和筛选策略。
3. 如果任务涉及出站 Webhook 配置或入站 HTTP 服务端点，请阅读 references/webhook-reference.md。

步骤 3：实现出站事件监听器（如适用）

1. 阅读 assets/event-listener.template.ts，将其作为起始脚手架。
2. 在应用程序的 main.ts（或 main.js）控制器中，使用 lib-event 的 listener() 函数注册事件监听器。
3. 使用 type 参数匹配目标节点事件的模式（例如 node.pushed、node.created、node.updated、node.deleted）。
4. 在回调中检查 event.data.nodes[].path，按路径筛选事件，以限制对目标内容树的处理。
5. 如果监听器需要调用外部 HTTP 端点，请在回调中使用 lib-httpClient 的 request() 函数，或将任务委派给后台任务。
6. 对于长时间运行的处理，请使用 lib-task 的 executeFunction()，将工作从事件回调委派给后台任务，以避免阻塞事件线程。
7. 阅读 references/examples.md，了解完整的集成模式，包括 CDN 缓存失效、搜索重新索引和通知分发。

步骤 4：配置出站 Webhook（如适用）

1. 阅读 references/webhook-reference.md，了解 com.enonic.xp.webhooks.cfg 配置格式。
2. 在 XP_HOME/config/com.enonic.xp.webhooks.cfg 创建或更新文件，添加指定目标 URL 和事件类型的 Webhook 条目。
3. 验证配置的事件类型是否与预期的内容生命周期事件相匹配。
4. Webhook 目标地址请使用 HTTPS URL。
5. 切勿将实际密钥值写入配置文件或源代码。 请使用描述性的占位符令牌（例如 REPLACE_WITH_CDN_SECRET），并指示操作人员通过文件之外的方式替换为真实凭据。密钥必须由操作人员通过安全部署流水线、环境变量或密钥管理工具进行管理，不得提交到文件中。 步骤 5：实现入站 webhook 端点（如适用）
6. 阅读 assets/http-service.template.ts，将其作为起始脚手架。
7. 在 src/main/resources/services/<serviceName>/<serviceName>.ts 创建 HTTP 服务控制器。
8. 导出 post(req) 函数，从 req.body 解析传入的 JSON 负载。
9. 在解析前，拒绝超出合理大小限制（例如 1 MB）的负载。
10. 在处理入站负载前，通过检查必需字段、身份验证标头或 HMAC 签名来验证负载。
11. 在内容操作中使用外部负载中的字符串字段之前，先对其进行清理：去除首尾空格、限制最大长度、剥离或转义 HTML/脚本内容，并拒绝包含路径遍历序列（..、/、\）的值。
12. 使用预期字段名称的允许列表，而不要将原始负载对象传递给内容 API。
13. 返回适当的 HTTP 状态码：成功时返回 200，负载格式错误时返回 400，身份验证失败时返回 401，负载过大时返回 413，出现意外错误时返回 500。
14. 当入站负载触发内容创建或修改时，在上下文运行中使用 lib-content 或 lib-node API，以确保权限正确。绝不要将未经清理的外部值用作内容名称、路径或键。

步骤 6：使用 lib-task 接入异步处理（如适用）

1. 当事件处理或 webhook 处理需要执行繁重或耗时的工作时，将其封装在 lib-task 的 executeFunction() 中。
2. 使用 progress() 报告长时间运行的任务进度，以便监控。
3. 阅读 references/event-reference.md，了解任务事件生命周期（task.submitted、task.updated、task.finished、task.failed）。

步骤 7：验证集成

1. 执行 node scripts/find-enonic-targets.mjs .，确认项目仍能正确解析。
2. 验证事件监听器注册位于应用程序的 main.ts 或 main.js 文件中，该文件会在应用程序启动时运行。
3. 确认出站 HTTP 调用使用 HTTPS，并包含对网络故障和非 2xx 响应的错误处理。
4. 确认生成的源代码或配置文件中不包含实际的机密值、API 密钥或凭据——只包含占位令牌。
5. 确认入站 webhook 端点在将外部负载中的字段传递给内容 API 前，会对所有字段进行清理并应用允许列表。
6. 如果创建了 webhook 配置文件，确认事件类型模式与预期触发条件相符。
7. 运行工作区构建，确认没有编译错误。
8. 如果事件未触发、webhook 投递失败或入站请求遭到拒绝，请阅读 references/troubleshooting.md。

错误处理

• 如果 node scripts/find-enonic-targets.mjs . 未找到项目，请确认 build.gradle 引用了 com.enonic.xp 插件，或存在 src/main/resources/site/ 目录。
• 如果注册监听器后事件仍未触发，请阅读 references/troubleshooting.md，检查监听器注册位置、事件类型模式，以及集群事件与本地事件的作用范围。
• 如果出站 HTTP 调用失败，请验证目标 URL、XP 实例的网络访问情况，以及操作人员是否已将占位令牌替换为真实凭据。
• 如果入站 webhook 请求返回 404，请确认服务控制器路径符合 services/<name>/<name>.ts 格式，且应用程序已部署。
• 如果后台任务无声失败，请使用 taskLib.list() 检查任务状态，并查看任务函数中的错误日志。