---
title: "当 LemonX 操作在 WordPress 内发生时触发外部工作流程。"
url: https://cn.harlemon.com/developers/webhooks/
description: "开发商/网络钩子 LemonX 开发人员·Webhooks 当 LemonX 操作在 WordPress 内发生时触发外部工作流程。 LemonX Webhook 允许开发人员将实时事件从 WordPress 发送到外部系统。创建内容、AEO 分析完成、翻译排队、应用 MCP 预览、提交索引请求、生成报告或许可证状态更"
author: "vincenter20@gmail.com"
date_published: 2026-07-06T08:50:54+00:00
date_modified: 2026-07-07T01:06:28+00:00
language: zh-Hans
type: page
generator: LemonX AEO 1.4.12
---

# 当 LemonX 操作在 WordPress 内发生时触发外部工作流程。

LemonX 开发人员·Webhooks

# 当 LemonX 操作在 WordPress 内发生时触发外部工作流程。

LemonX Webhook 允许开发人员将实时事件从 WordPress 发送到外部系统。创建内容、AEO 分析完成、翻译排队、应用 MCP 预览、提交索引请求、生成报告或许可证状态更改时，LemonX 可以通知您自己的应用程序、仪表板和自动化工具。

在 LemonX、WordPress、CRM、客户门户、机构仪表板、分析系统、Make、n8n、Zapier 式自动化、Slack 警报和内部平台之间构建事件驱动的工作流程。

探索 Webhook 事件
查看安全模型
请参阅 Webhook 示例

事件驱动 · 签名有效负载 · 重试感知 · 专为 WordPress AI 自动化而构建

## 什么是 LemonX Webhook？

LemonX Webhook 是从 LemonX 支持的 WordPress 站点发送到外部 URL 的出站事件通知。 They allow other systems to react when important LemonX actions occur.

您的系统无需不断轮询 REST API 来检查是否发生更改，而是可以在更改实际发生时接收事件。

### 实时事件传递

当 LemonX 工作流程创建、更新、完成、失败或需要审核时接收通知。

### 适用于 LemonX 产品

Webhooks 可以涵盖 AEO、Code、Verto、MCP、Pro、云网关、报告、任务和内容工作流程。

### 专为自动化而打造

将 LemonX 连接到 CRM、客户仪表板、分析系统、Slack、Make、n8n、内部工具或自定义应用程序。

### 设计安全

在系统信任 Webhook 有效负载之前，应对其进行签名、时间戳和验证。

为什么这很重要

## 现代 WordPress 工作流程不应等待手动检查。

AI 支持的网站会生成许多事件：新草稿、内容预览、SEO 分析、翻译任务、索引请求、MCP 操作、报告生成、使用更改和许可证更新。如果没有 webhook，外部系统必须反复询问 WordPress 是否有任何更改。

**Webhook 逆转了这一流程。 LemonX 会在重要事件发生时告诉您的系统。**

### 没有 Webhooks

- 外部系统必须重复轮询 API。
- 自动化运行延迟或错过更改。
- 报告需要手动刷新。
- 客户端仪表板显示过时的数据。
- 失败的任务可能会被忽视。
- 团队依靠人工检查。
- 复杂的工作流程变得更难维护。

### 使用 LemonX Webhook

- 外部系统近乎实时地做出反应。
- 客户门户自动更新。
- Slack 警报可以通知团队。
- 翻译完成可以触发审核。
- MCP 操作可以从外部记录。
- 报告准备就绪后即可交付。
- 自动化平台可以立即开始下一步。

使用案例

## 您可以使用 LemonX Webhooks 构建什么？

使用案例1

### 代理客户仪表板

每当内容、SEO、翻译、报告或 MCP 活动发生变化时，将事件从客户端 WordPress 站点发送到中央机构仪表板。

##### 事件示例

- 内容更新
- aeo.analysis_completed
- verto.translation_completed 已完成
- MCP.action_completed
- 报告生成
- 许可证.status_changed

**结果：**您的代理仪表板保持更新，无需不断轮询每个客户网站。

用例2

### Slack 或团队通知

当重要工作流程完成、失败或需要关注时通知您的团队。

##### 事件示例

- 任务失败
- 翻译.review_required
- MCP.preview_created
- 索引.已提交
- 报告生成
- 配额警告

**结果：**当 AI、翻译、索引或报告工作流程需要审核时，团队可以更快地采取行动。

用例 3

### 内容审批工作流程

当 AI 创建草稿、提出更新或生成预览时触发外部审批系统。

##### 事件示例

- 内容.draft_created
- 内容.preview_created
- MCP.preview_created
- seo.preview_created
- 翻译.preview_created

**结果：**编辑、客户或经理可以在应用之前查看 AI 生成的更改。

用例 4

### 多语言发布工作流程

当翻译排队、完成、失败或准备好供人工审阅时发送事件。

##### 事件示例

- verto.translation_queued
- verto.translation_completed 已完成
- verto.translation_failed
- verto.translation_review_required
- verto.seo_fields_ generated

**结果：**全球内容团队可以协调跨语言和跨地区的多语言发布。

用例 5

### AI 活动审核日志记录

将 MCP 工具调用、应用的预览和 AI 驱动的更改发送到外部审计或安全系统。

##### 事件示例

- MCP.tool_称为
- MCP.preview_created
- MCP.preview_applied
- MCP.action_failed
- MCP.session_connected
- MCP.session_revoked

**结果：**开发人员和安全团队可以跟踪 AI 代理在 WordPress 内所做的事情。

用例 6

### 搜索和索引自动化

当 AEO 分析完成、提交索引请求或生成搜索报告时通知外部系统。

##### 事件示例

- aeo.analysis_completed
- aeo.opportunity_Detected
- aeo.indexing_subscribed
- aeo.schema_ generated
- aeo.报告生成

**结果：**SEO 团队可以将 LemonX 活动与报告、项目管理和活动跟踪工具连接起来。

用例 7

### 许可证和使用监控

将许可证、权利、配额和使用事件发送到帐户仪表板或计费相关系统。

##### 事件示例

- 许可证激活
- 许可证已过期
- 许可证.status_changed
- 权利.更新
- 用法.quota_warning
- 用量.quota_exceeded

**结果：**团队可以跨站点监控帐户访问、计划限制和高级功能可用性。

活动类别

## 跨 LemonX Suite 的 Webhook 事件。

LemonX Webhooks 应遵循与 LemonX 生态系统相同的产品结构。每个产品都可以发出与其自身工作流程相关的事件，而共享系统事件则处理任务、报告、许可证、使用情况和安全性。

第 1 类

### 内容活动

#### 帖子、页面、草稿和内容更新的事件。

当 WordPress 内容通过 LemonX 工作流程发生更改时，内容事件会通知外部系统。

##### 事件示例

- 内容.draft_created
- 内容.创建
- 内容更新
- 内容.preview_created
- 内容.preview_applied
- 内容.已发布
- 内容.status_changed
- 内容已删除
- content.migration_preview_created
- 内容.migration_completed

##### 示例用例

- 创建草稿时更新客户端仪表板。
- 当 AI 生成内容预览时通知编辑者。
- 页面迁移完成时触发 QA。
- 将发布的内容发送到外部营销系统。
- 记录 WordPress 之外的重要内容更改。

第2类

### LemonX AEO 活动

#### SEO、AEO、AI 可见性和索引工作流程的事件。

当搜索优化工作流程产生新结果、建议或操作时，AEO 事件会通知外部系统。

##### 事件示例

- aeo.analysis_started
- aeo.analysis_completed
- aeo.analysis_failed
- aeo.opportunity_Detected
- aeo.schema_ generated
- aeo.internal_links_suggested
- aeo.indexing_queued
- aeo.indexing_subscribed
- aeo.indexing_failed
- aeo.报告生成
- aeo.引用_检测到
- aeo.brand_mention_Detected

##### 示例用例

- 将 SEO 机会发送到项目管理工具中。
- AEO 审核完成后通知团队。
- 提交索引后更新仪表板。
- 检测到引用时触发报告。
- 在客户端活动时间线中记录 SEO 操作。

第3类

### LemonX Code 活动

#### AI 页面生成、模板、OCR 和迁移工作流程的事件。

当创建或更新 AI 生成的内容、页面结构、模板或迁移任务时，Code 事件会通知外部系统。

##### 事件示例

- 代码.page_ Generation_started
- code.page_ Generation_completed
- code.page_ Generation_failed
- 代码.section_生成
- 代码.template_applied
- 代码.knowledge_query_completed
- 代码.ocr_started
- 代码.ocr_completed
- 代码.ocr_失败
- code.migration_preview_created
- 代码.migration_completed

##### 示例用例

- 当着陆页草稿准备好时通知团队。
- 将页面生成结果发送到代理仪表板。
- OCR 处理后触发审核。
- 记录迁移工作流程。
- 当生成的页面需要批准时创建任务。

第 4 类

### LemonX Verto 活动

#### 翻译和多语言 SEO 工作流程的活动。

当内容进入翻译、翻译完成、需要审阅或生成多语言 SEO 字段时，Verto 事件会通知外部系统。

##### 事件示例

- verto.translation_queued
- verto.translation_started
- verto.translation_completed 已完成
- verto.translation_failed
- verto.translation_review_required
- verto.translation_applied
- verto.语言_添加
- verto.language_disabled
- verto.slug_translated
- verto.hreflang_updated
- verto.seo_fields_ generated
- verto.report_ generated

##### 示例用例

- 需要审核时通知译者。
- 触发多语言质量检查清单。
- 更新客户端仪表板语言覆盖范围。
- 将翻译内容状态发送到外部系统。
- 批准后提交翻译的 URLs 进行索引。

第5类

### LemonX MCP 活动

#### AI 代理会话、工具调用、预览和应用操作的事件。

当 AI 客户端连接、调用工具、创建预览、应用更改或遇到错误时，MCP 事件会通知外部系统。

##### 事件示例

- MCP.session_connected
- MCP.session_disconnected
- MCP.session_revoked
- MCP.tool_称为
- MCP.tool_failed
- MCP.preview_created
- MCP.preview_applied
- MCP.preview_discarded
- MCP.permission_denied
- MCP.action_completed
- MCP.action_failed
- MCP.log_created

##### 示例用例

- 将 MCP 活动发送到安全日志。
- 当 AI 应用更改时通知网站所有者。
- 跟踪哪个 AI 客户端执行了操作。
- 建立外部批准时间表。
- 监控失败的 AI 工具调用。
- 当权限拒绝敏感操作时提醒管理员。

第六类

### LemonX Pro 和云网关事件

#### 许可证、权利、使用和云连接工作流程的事件。

当帐户级别、许可证级别或云连接状态发生变化时，Pro 和云网关事件会通知外部系统。

##### 事件示例

- 许可证激活
- 许可证.停用
- 许可证已过期
- 许可证更新
- 许可证.status_changed
- 权利.更新
- 云连接
- 云.断开连接
- 云同步完成
- 云同步失败
- 使用记录
- 用法.quota_warning
- 用量.quota_exceeded
- 更新可用
- 更新.已安装

##### 示例用例

- 更新帐户仪表板。
- 许可证到期时通知网站所有者。
- 在达到使用限制之前警告机构。
- 跟踪云同步问题。
- 记录高级功能的使用情况。
- 触发内部计费或帐户工作流程。

第7类

### 报告事件

#### 生成报告和导出的事件。

当 LemonX 生成、更新或导出报告时，报告事件会通知外部系统。

##### 事件示例

- 报告.创建
- 报告生成
- 报告失败
- 报告.导出
- 报告.发送
- 报告.存档
- 报告.预定

##### 示例用例

- 将生成的报告发送到客户门户。
- 报告准备好后通知客户经理。
- 将导出的报告存储在外部系统中。
- 触发电子邮件传送。
- 创建定期机构报告工作流程。

第8类

### 任务和队列事件

#### 长时间运行的后台作业的事件。

任务事件帮助开发人员跟踪可能需要时间的工作流程，例如翻译、AI 生成、OCR、索引、报告、迁移和云同步。

##### 事件示例

- 任务.创建
- 任务.开始
- task.completed
- 任务失败
- 任务已取消
- 队列.暂停
- 队列.恢复
- 队列.backlog_warning
- queue.completed

##### 示例用例

- 监视长时间运行的 AI 作业。
- 通知管理员后台任务失败。
- 触发重试工作流程。
- 在外部仪表板中显示队列状态。
- 检测托管或性能问题。

第9类

### 安全事件

#### 敏感操作和访问更改的事件。

当身份验证、权限、API 密钥、Webhook 或 MCP 访问更改时，安全事件会通知外部系统。

##### 事件示例

- security.api_key_created
- security.api_key_revoked
- security.permission_changed
- security.login_required
- security.invalid_signature
- security.webhook_failed
- security.MCP_access_changed
- security.protected_resource_blocked

##### 示例用例

- 将敏感事件发送到安全监控工具。
- 创建 API 密钥时提醒管理员。
- 跟踪已撤销的 MCP 会话。
- 记录失败的 Webhook 签名检查。
- 监视 AI 工具权限的更改。

有效载荷结构

## 清晰的有效负载使 Webhook 易于处理。

Webhook 有效负载应该是可预测的、结构化的并且易于外部系统解析。每个事件应包括事件类型、传递 ID、时间戳、站点标识、资源数据和特定于事件的详细信息。

#### 有效负载示例

```
{
  "event": "MCP.preview_applied",
  "delivery_id": "lx_delivery_123456",
  "created_at": "2026-07-04T10:00:00Z",
  "site": {
    "id": "site_abc123",
    "url": "https://example.com",
    "name": "Example WordPress Site"
  },
  "actor": {
    "type": "user",
    "id": 12,
    "role": "administrator"
  },
  "source": {
    "product": "MCP",
    "client": "claude_desktop",
    "tool": "preview_apply"
  },
  "resource": {
    "type": "page",
    "id": 245,
    "url": "https://example.com/services",
    "title": "Services"
  },
  "data": {
    "preview_id": "lx_preview_789",
    "action": "content_update",
    "status": "applied"
  }
}
```

### 推荐的有效负载字段

`event``delivery_id``created_at``site``actor``source``resource``data``api_version``signature_context``retry_count``test_mode`

标头

## 使用标头来验证和处理交付。

#### 推荐的标头

```
X-LemonX-Event: MCP.preview_applied
X-LemonX-Delivery: lx_delivery_123456
X-LemonX-Timestamp: 1783178400
X-LemonX-Signature: sha256=...
X-LemonX-Site: site_abc123
X-LemonX-Version: 1
User-Agent: LemonX-Webhooks/1.0
```

### 标头详细信息

#### X-LemonX-事件

事件类型，例如 content.updated 或 verto.translation_completed。

#### X-LemonX-交货

本次投递尝试的唯一 ID。使用它进行重复数据删除和调试。

#### X-LemonX-时间戳

发送 Webhook 的时间。用它来防止重放攻击。

#### X-LemonX-签名

使用 webhook 密钥生成的签名。在信任有效负载之前验证它。

#### X-LemonX-网站

与事件关联的站点标识。

#### X-LemonX-版本

Webhook 负载版本。

Webhook 安全性

## 在验证 Webhook 之前，切勿信任它。

Webhook 端点是一个公共 URL，它从 LemonX 接收数据。由于 public URLs 可以接收来自任何人的请求，因此您的系统应在处理每个交付之前对其进行验证。

要求1

### 使用 HTTPS

Webhook 端点应使用 HTTPS。不要将敏感事件数据发送到普通 HTTP 端点。

要求2

### 验证签名

每个 Webhook 应包含使用共享密钥生成的签名。您的系统应该重新创建签名并安全地进行比较。

要求3

### 检查时间戳新鲜度

拒绝具有旧时间戳的 Webhook 传送，以降低重放攻击风险。

要求4

### 删除重复的交付 ID

存储已处理的交付 ID，以便重复尝试不会触发重复操作。

要求5

### 验证事件类型

仅处理系统期望的事件类型。

要求6

### 验证有效负载架构

不要假设每个有效负载都是有效的。处理前检查必填字段。

要求7

### 保护您的端点

对 Webhook 端点进行速率限制、拒绝无效签名并记录可疑请求。

验证

## Webhook 签名验证示例。

确切的实现可能有所不同，但一般模式是相同的：结合时间戳和原始有效负载，使用共享密钥生成 HMAC 签名，然后将其与签名标头进行比较。

#### 逻辑示例

```
signed_payload = timestamp + "." + raw_body
expected_signature = HMAC_SHA256(webhook_secret, signed_payload)
compare expected_signature with X-LemonX-Signature
```

#### 示例 PHP 验证

```
function verify_lemonx_webhook( $raw_body, $timestamp, $signature_header, $secret ) {
    if ( empty( $raw_body ) || empty( $timestamp ) || empty( $signature_header ) || empty( $secret ) ) {
        return false;
    }

    $tolerance = 300;
    if ( abs( time() - (int) $timestamp ) > $tolerance ) {
        return false;
    }

    $signed_payload = $timestamp . '.' . $raw_body;
    $expected = 'sha256=' . hash_hmac( 'sha256', $signed_payload, $secret );

    return hash_equals( $expected, $signature_header );
}
```

**重要提示：**始终根据原始请求正文验证签名，而不是重新编码的 JSON 版本。重新编码 JSON 可能会更改空格或顺序并导致签名不匹配。

交付生命周期

## 触发 Webhook 时会发生什么？

1

### 事件发生

LemonX 工作流程会生成一个事件，例如翻译完成、应用 MCP 预览或生成报告。

2

### Webhook 订阅匹配

LemonX 检查哪些 Webhook 端点订阅了该事件类型。

3

### 有效负载已创建

LemonX 构建带有事件详细信息的结构化 JSON 有效负载。

4

### 签名已生成

LemonX 使用 webhook 密钥对有效负载进行签名。

5

### 活动已交付

LemonX 向配置的端点发送 HTTP POST 请求。

6

### 接收方验证请求

您的系统检查签名、时间戳、事件类型和有效负载结构。

7

### 接收方返回状态

如果事件被接受，您的端点将返回 2xx 响应。

8

### 如果需要重试

如果投递失败，LemonX可以根据重试规则重试。

9

### 交付已记录

LemonX 存储交付状态以进行调试和可见性。

重试

## Webhook 传递应该处理临时故障。

Webhook 端点可能因多种原因而失败：网络问题、停机、速率限制、部署窗口或临时错误。 LemonX 应支持失败交付的重试行为。

### 推荐的重试规则

- 重试 5xx 响应。
- 连接超时重试。
- 出现临时网络故障时重试。
- 不要重试大多数 4xx 响应。
- 使用指数退避。
- 限制最大重试次数。
- 存储递送尝试历史记录。
- 允许从管理 UI 手动重新发送。

### 重试计划示例

- 尝试 1：立即
- 尝试 2：1 分钟后
- 尝试 3：5 分钟后
- 尝试 4：15 分钟后
- 尝试 5：1 小时后
- 尝试 6：6 小时后

### 端点响应建议

- 仅在系统接受事件后才返回 2xx。
- 当请求无效且不应重试时返回 4xx。
- 当请求稍后重试时返回 5xx。

网络钩子管理

## 开发人员需要对 Webhook 端点进行明确的控制。

LemonX 应该提供一种创建、测试、禁用、删除和检查 webhooks 的方法。这可以通过 WordPress 管理 UI、REST API 或云网关获得，具体取决于产品配置。

### 推荐的 Webhook 字段

名称端点 URL订阅事件秘密状态创建者：创建日期最后一次交货最后的成功最后一次失败重试次数描述测试模式环境允许的产品

### Webhook 操作

- 创建网络钩子
- 更新网络钩子
- 禁用网络钩子
- 删除网络钩子
- 旋转秘密
- 发送测试事件
- 重发发送失败
- 查看发货历史记录
- 过滤事件
- 启用测试模式

REST API

## 以编程方式管理 Webhook。

开发人员可以使用 REST API 端点来注册和管理 Webhook。这些端点名称是示例，应与最终的 LemonX 实现相匹配。

```
GET    /wp-json/lemonx/v1/webhooks
POST   /wp-json/lemonx/v1/webhooks
GET    /wp-json/lemonx/v1/webhooks/{id}
PATCH  /wp-json/lemonx/v1/webhooks/{id}
DELETE /wp-json/lemonx/v1/webhooks/{id}
POST   /wp-json/lemonx/v1/webhooks/{id}/test
POST   /wp-json/lemonx/v1/webhooks/{id}/rotate-secret
GET    /wp-json/lemonx/v1/webhooks/{id}/deliveries
POST   /wp-json/lemonx/v1/webhooks/deliveries/{delivery_id}/resend
```

#### 创建请求示例

```
{
  "name": "Agency Dashboard",
  "url": "https://agency.example.com/lemonx/webhook",
  "events": [
    "content.updated",
    "aeo.analysis_completed",
    "verto.translation_completed",
    "MCP.preview_applied",
    "report.generated"
  ],
  "status": "active"
}
```

#### 创建响应示例

```
{
  "success": true,
  "data": {
    "id": "wh_123",
    "name": "Agency Dashboard",
    "url": "https://agency.example.com/lemonx/webhook",
    "status": "active",
    "events": [
      "content.updated",
      "aeo.analysis_completed",
      "verto.translation_completed",
      "MCP.preview_applied",
      "report.generated"
    ],
    "secret_preview": "whsec_****abcd"
  }
}
```

处理程序示例

## 一个简单的 PHP webhook 接收器。

```

```

过滤

## 仅订阅您的系统需要的事件。

繁忙的 WordPress 站点可以举办许多活动。开发人员应避免将所有可能的事件发送到每个端点。相反，创建集中的 Webhook 订阅。

### 代理仪表板 webhook

`content.updated``aeo.analysis_completed``verto.translation_completed``report.generated``license.status_changed`

### 安全审核 Webhook

`MCP.tool_called``MCP.preview_applied``security.api_key_created``security.permission_changed``security.webhook_failed`

### 翻译工作流程网络钩子

`verto.translation_queued``verto.translation_completed``verto.translation_failed``verto.translation_review_required`

### 报告网络钩子

`report.generated``report.exported``report.failed``task.failed`

### 使用情况监控 webhook

`usage.recorded``usage.quota_warning``usage.quota_exceeded``license.expired``entitlement.updated`

测试

## 在依赖 Webhook 自动化之前进行测试。

1

### 创建测试端点

在开发过程中使用暂存端点或 Webhook 检查工具。

2

### 发送测试事件

使用 LemonX webhook 测试操作发送示例负载。

3

### 验证签名逻辑

确保您的接收者正确验证时间戳和签名。

4

### 测试重试

返回临时 500 响应并确认重试行为。

5

### 测试重复交付

发送相同的送货 ID 两次，并确认您的系统不会处理两次。

6

### 测试事件过滤

确认您的端点仅接收其订阅的事件。

7

### 测试生产秘密

使用单独的 Webhook 密钥进行暂存和生产。

自动化平台

## 将 LemonX 与 Make、n8n、Zapier 风格的工作流程和内部系统连接起来。

Webhook 使将 LemonX 工作流程与自动化平台连接起来成为可能。当 LemonX 事件发生时，自动化平台可以接收有效负载并触发下一步。

### 自动化示例 1：翻译完成 → 通知审稿人

1. LemonX 发送 verto.translation_completed。
2. 自动化将 Slack 消息发送给翻译人员。
3. 审阅者检查翻译后的页面。
4. 审批任务已创建。

### 自动化示例 2：检测到 AEO 机会 → 创建项目任务

1. LemonX 发送 aeo.opportunity_detected。
2. 自动化在项目管理系统中创建任务。
3. SEO 团队审查机会。
4. 内容更新已安排。

### 自动化示例 3：应用 MCP 预览 → 记录到审核表

1. LemonX 发送 MCP.preview_applied。
2. 自动化将行添加到外部审计数据库。
3. 经理可以查看 AI 应用的更改。

### 自动化示例 4：生成报告 → 发送客户电子邮件

1. LemonX 发送生成的报告。
2. 自动化获取报告或使用有效负载数据。
3. 客户电子邮件已准备或发送。

### 自动化示例 5：配额警告 → 通知帐户所有者

1. LemonX 发送usage.quota_warning。
2. 自动化提醒帐户所有者。
3. 团队决定是否升级或减少使用。

最佳实践

## 构建可靠的 Webhook 集成。

### 最佳实践 1：验证每个 Webhook

不处理未签名或无效的 Webhook 请求。

### 最佳实践2：使用幂等性

可以重试 Webhook 传送。使用交付 ID 来防止重复处理。

### 最佳实践 3：快速响应

尽快回复。对于缓慢的工作，请在您自己的系统中对作业进行排队。

### 最佳实践 4：缩小订阅范围

仅订阅您的端点需要的事件。

### 最佳实践 5：存储交付日志

记录交付 ID、事件类型、时间戳和处理状态。

### 最佳实践 6：分离演出和制作

针对不同的环境使用不同的端点和秘密。

### 最佳实践 7：轮换机密

当团队成员发生变化或秘密可能泄露时，轮换 Webhook 秘密。

### 最佳实践8：优雅地处理未知事件

当 LemonX 添加新事件类型时，您的系统不应崩溃。

### 最佳实践 9：不要单独信任有效负载

验证签名、时间戳、事件类型和必填字段。

### 最佳实践 10：使用 REST API 获取后续详细信息

Webhook 有效负载应包含足够的信息来做出反应。如果您的系统需要完整的详细信息，请使用 REST API 获取最新的资源状态。

## 常见的 Webhook 集成错误。

**不验证签名**这允许任何人向您的端点发送虚假事件。

**处理重复交付**如果您不存储递送 ID，重试可能会导致重复操作。

**在 webhook 请求中执行缓慢的工作**长时间处理可能会导致超时。将慢速任务排队并快速响应。

**订阅每个事件**太多不必要的事件会产生噪音并增加失败风险。

**到处使用相同的秘密**登台、生产和不同的系统应该使用单独的秘密。

**忽略失败的交付**失败的交付应该是可见的并且可以重试。

**将 webhook 视为保证顺序**事件可能会无序到达。使用时间戳和资源状态检查。

**不验证负载版本**Webhook 格式可能会演变。检查版本字段并妥善处理更改。

Webhooks 与 REST API

## 使用 webhooks 做出反应。使用 REST API 来请求。

### REST API

您的系统向 LemonX 请求数据或触发操作。

#### 最适合

- 获取报告
- 创建草稿
- 检查许可证状态
- 正在提交 URLs
- 读取任务状态
- 管理 Webhook 设置
- 构建仪表板

### 网络钩子

LemonX 会在发生某些情况时通知您的系统。

#### 最适合

- 对事件做出反应
- 发送警报
- 更新仪表板
- 启动自动化
- 记录 AI 操作
- 触发外部审查
- 更改后同步状态

**摘要：**REST API 是基于请求的。 Webhook 是基于事件的。最重要的集成应该同时使用两者。

MCP 活动

## 当 MCP 操作可观察时，它们会变得更有用。

当 AI 代理通过 LemonX MCP 操作 WordPress 时，Webhooks 可以使这些操作对外部系统可见。

### 示例 MCP Webhook 流程

1. Claude 通过 MCP 连接到 WordPress。
2. AI 读取登陆页面。
3. AI 创建预览更新。
4. 用户批准更新。
5. LemonX 应用更新。
6. Webhook 将 MCP.preview_applied 发送到外部审计系统。
7. 代理仪表板记录了变化。

**为什么它很重要：**AI 操作不应消失在后台。 Webhooks 使 MCP 工作流程可观察、可审核并且更容易与人类团队协调。

事件参考

## 建议的事件命名约定。

#### 图案

```
product.resource_action
```

#### 示例

```
content.draft_created
content.updated
aeo.analysis_completed
verto.translation_completed
MCP.preview_applied
report.generated
license.status_changed
usage.quota_warning
security.api_key_revoked
```

### 命名指南

- 使用小写。
- 使用点来分隔产品和操作。
- 对已完成的事件使用过去时动作。
- 使用清晰的名称来描述所发生的事情。
- 保持事件名称在各个版本中保持稳定。
- 避免让某一事件具有过多的含义。

错误处理

## 使失败的交付易于调试。

| 状态 | 含义 | 建议采取的行动 |
| --- | --- | --- |
| 待定 | 尚未尝试交付 | 等等 |
| 已交付 | 端点返回2xx | 无需采取任何行动 |
| 重试 | 发送失败，将重试 | 检查端点日志 |
| 失败了 | 多次尝试后交付失败 | 手动重新发送或修复端点 |
| 残疾人 | Webhook 端点已禁用 | 检查配置 |
| 签名失败 | 收件人拒绝签名 | 检查秘密 |
| 超时 | 端点未及时响应 | 更快地响应或排队工作 |
| 无效的网址 | 端点 URL 无效 | 修复 URL |
| 速率限制 | 端点拒绝了太多请求 | 减少活动量 |

### 推荐的调试字段

交货编号事件类型端点 URLHTTP状态尝试次数最后一个错误下次重试时间有效负载预览创建时间上次尝试时间

隐私

## 仅发送集成所需的事件数据。

Webhook 有效负载应包含足够的数据来识别和处理事件，但应避免发送不必要的敏感信息。

### 推荐的有效负载策略

- 如果可能，请包括 ID 和 URLs。
- 除非需要，请包含摘要而不是完整内容。
- 使用 REST API 后续调用来获取完整的资源详细信息。
- 避免发送私有 API 密钥。
- 避免发送密码或秘密。
- 避免发送不相关的用户数据。
- 尊重网站隐私设置。
- 允许管理员选择发送哪些事件。

**示例：**对于 content.updated，Webhook 可以发送内容 ID、标题、URL、状态和更新类型。如果外部系统需要完整的内容主体，它可以通过适当的身份验证调用 REST API 。

## 围绕 LemonX 构建事件驱动的工作流程。

使用 Webhook 将 WordPress AI 操作、SEO 工作流程、翻译进度、MCP 活动、报告和云事件与您自己的工具和自动化系统连接起来。

[查看 Webhook 示例](https://cn.harlemon.com/developers/examples/)
[阅读 REST API 文档](https://cn.harlemon.com/developers/rest-api/)

## Webhook 常见问题解答

**什么是 LemonX Webhook？**

LemonX Webhooks 是当 LemonX 工作流创建、更新、完成、失败或需要审核时从 WordPress 发送到外部系统的事件通知。

**我什么时候应该使用 webhooks 而不是 REST API 轮询？**

当您的系统需要在发生某些情况时做出反应时，请使用 Webhook。仅当事件传递不可用或需要按需获取当前状态时才使用 REST API 轮询。

**Webhook 有效负载是否已签名？**

它们应该使用共享密钥进行签名，以便接收系统可以验证事件是否来自 LemonX。

**我可以只订阅部分活动吗？**

是的。 Webhook 订阅应该允许您选择特定的事件类型。

**如果我的端点出现故障，会发生什么情况？**

LemonX 应根据重试规则重试失败的交付，并显示交付历史记录以进行调试。

**我可以重新发送失败的 Webhook 吗？**

Webhook 管理 UI 或 API 应允许重新发送失败的传递。

**webhooks 可以与 MCP 一起使用吗？**

是的。当调用 AI 工具、创建预览、应用预览或操作失败时，MCP 事件可以通知外部系统。

**Webhook 可以触发 Make 或 n8n 工作流程吗？**

是的。 Webhook 是将 LemonX 与自动化平台（例如 Make、n8n 或自定义工作流程系统）连接的自然方式。

**Webhook 端点是否应该返回数据？**

通常不会。 Webhook 端点应快速确认收到。如果需要更多工作，请将其放入您自己的系统中。

**Webhooks 可以包含完整内容吗？**

They can, but it is often better to send resource IDs and summary data, then use the REST API to fetch full details when needed.

## 让您的系统在 WordPress 更改时做出反应。

LemonX Webhooks 将 AI、SEO、翻译、MCP 和云工作流程转换为外部系统可以理解并采取行动的事件。

[继续示例](https://cn.harlemon.com/developers/examples/)
[查看认证指南](https://cn.harlemon.com/developers/)
[探索REST API](https://cn.harlemon.com/developers/rest-api/)

[MCP 工具](https://cn.harlemon.com/developers/mcp-tools/)
[REST API](https://cn.harlemon.com/developers/rest-api/)
[挂钩和过滤器](https://cn.harlemon.com/developers/)
[认证](https://cn.harlemon.com/developers/)
[云网关](https://cn.harlemon.com/developers/)
[开发者主页](https://cn.harlemon.com/developers/)

[WhatsApp+44 7724 592551](https://wa.me/447724592551)
