Webhook 管理：创建、测试与认证

Webhook 让 AgencyHandy 能够在发生变化的那一刻将数据推送到您的外部系统 — 无需轮询。当配置的事件触发时（例如，订单被更新或工单被创建），AgencyHandy 会向您指定的端点 URL 发送一个包含 JSON 负载的 HTTP POST 请求。这使得外部工具（如 CRM、账单系统或自定义仪表板）能够与您的 AgencyHandy 工作区实时保持同步。

Business Pro 计划的工作区每个计费周期支持最多 30,000 个 Webhook 事件。在设置高频自动化之前，请检查您的计划限制。

支持的事件

您可以为 Webhook 订阅以下任意组合的事件：

类别	事件
服务	已创建、已更新、已删除
订单	已创建、已更新、已删除
任务	已创建、已分配、已完成、已更新
发票	状态已变更
客户 / 用户	新客户已添加、客户/用户已删除
提案	已发送、已接收、已接受、已拒绝
工单	已创建、已分配、状态已变更
付款	已收到、已失败
服务套餐	已创建、已更新、已删除

创建 Webhook

导航至 Webhook 管理

在左侧边栏中，前往 集成 → Webhook 管理。

验证您的令牌

点击管理按钮以验证您的 Webhook 令牌。该令牌用于对出站负载进行签名，以便您验证其来源是否为 AgencyHandy。

创建新的 Webhook

点击 创建新 Webhook 以打开 Webhook 配置表单。

输入端点 URL

在 端点 URL 字段中，输入接收 Webhook 数据的外部系统 URL。这必须是一个可公开访问的 POST 端点。

选择内容类型

选择 JSON 作为内容类型。AgencyHandy 以 application/json 格式发送所有 Webhook 负载。

选择 Webhook 事件

选择所有应触发此 Webhook 的事件。您可以从多个类别中选择事件 — 例如，订单：已创建 和 发票：状态已变更 可以同时指向同一个端点。

激活 Webhook

切换启用单选按钮。启用后，AgencyHandy 将实时向您的端点传送所有已选事件的负载。

保存配置

检查您的设置，然后点击保存。Webhook 将出现在列表中并立即开始传送事件。

测试 Webhook

创建 Webhook 后，发送一个测试负载以确认您的端点可访问且能正确处理数据。

打开 Webhook

在 Webhook 管理列表中，点击您要测试的 Webhook。

点击测试事件

在 Webhook 详情页面上点击 测试事件 按钮。

选择测试事件

从该 Webhook 配置的事件列表中选择一个示例事件（例如，订单：已创建）。

发送测试负载

点击发送。AgencyHandy 将向您的端点 URL 发布一个示例负载。

验证结果

检查您的外部系统以确认测试负载已到达并按预期处理。在 AgencyHandy 中，点击进入该 Webhook 查看其历史记录 — 您可以查看完整请求、端点返回的响应，以及在需要时重新传送任何历史事件。

在设置过程中，使用 Webhook.site 或 RequestBin 之类的工具作为临时端点，以便在接入真实系统之前检查确切的负载结构。

验证 Webhook 负载

AgencyHandy 的每个出站 Webhook 请求都包含一个签名标头，您的端点可以使用它来验证负载是否真实且未被篡改。

签名标头

x-ah-sig: <signature>

AgencyHandy 在每个 Webhook 请求中添加此标头。从传入请求中提取该值并将其传递给验证端点。

验证 Webhook 签名

发送以下请求以确认负载的真实性：

POST https://api.agencyhandy.com/api/v1/webhooks/verify-signature
Content-Type: application/json

string

必填

接收事件的 Webhook ID。在 AgencyHandy 的 Webhook 详情页面中可以找到此 ID。

string

必填

传入 Webhook 请求中 x-ah-sig 标头的值。

string

必填

AgencyHandy Webhook 详情页面上显示的 Webhook 密钥。

object

必填

从 AgencyHandy Webhook 请求中收到的原始 JSON 主体。

const url = 'https://api.agencyhandy.com/api/v1/webhooks/verify-signature';

const postData = {
  webhookId: 'your_webhook_id',
  signature: 'your_signature',   // value of x-ah-sig header
  secret: 'your_webhook_secret',
  payload: {},                   // the parsed JSON body from AgencyHandy
};

const response = await fetch(url, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(postData),
});

const data = await response.json();
console.log(data); // { "verification_status": "SUCCESS" }

curl -X POST https://api.agencyhandy.com/api/v1/webhooks/verify-signature \
  -H "Content-Type: application/json" \
  -d '{
    "webhookId": "your_webhook_id",
    "signature": "your_signature",
    "secret": "your_webhook_secret",
    "payload": {}
  }'

响应

string

签名有效时返回 SUCCESS。验证失败时返回 FAILED（HTTP 403）。

Success (200)

{
  "verification_status": "SUCCESS"
}

Failure (403)

{
  "type": "PermissionError",
  "status": 403,
  "verification_status": "FAILED"
}

请妥善保管您的 Webhook 密钥。定期轮换密钥，并在轮换后立即更新您的验证逻辑。切勿在客户端代码或公开仓库中暴露密钥。

重要说明

您的端点 URL 必须是可公开访问的 HTTPS POST URL。
如果您的端点暂时不可用，请在 AgencyHandy 中查看 Webhook 的历史面板 — 您可以直接从那里重新传送任何历史事件。
定期监控 Webhook 活动，以检测传送失败或未授权访问尝试。
多次失败的 Webhook 可能会被 AgencyHandy 暂停 — 请检查传送日志以尽早发现问题。

快速入门

工作区设置

CRM

服务与订单

提案与发票

团队与任务

表单与文件

账户与账单

付款

集成

Webhook 管理：创建、测试与认证

支持的事件

创建 Webhook

测试 Webhook

验证 Webhook 负载

签名标头

验证 Webhook 签名

重要说明

​支持的事件

​创建 Webhook

​测试 Webhook

​验证 Webhook 负载

​签名标头

​验证 Webhook 签名

​重要说明

支持的事件

创建 Webhook

测试 Webhook

验证 Webhook 负载

签名标头

验证 Webhook 签名

重要说明