跳转到内容
云词

Webhooks

实时接收项目中的关键事件通知

通过 Webhook，您可以实时接收云词项目中的关键事件通知，实现与第三方系统的集成。目前 Webhooks 仅支持项目级别的配置。

支持的事件

以下是云词当前支持的 Webhook 事件列表（文案相关）：

事件说明
key.created创建文案
key.deleted删除文案
key.updated更新文案
key.imported导入文案
key.tags.created批量添加标签
key.tags.deleted批量删除标签

请求说明

当发生您订阅的事件时，云词会向您配置的 URL 发送一个 POST 请求。

请求头 (Headers)

请求包含以下自定义 HTTP 头，用于验证和识别请求：

Header 字段说明示例值
User-Agent标识请求来源YunDict-Webhook/1.0
Content-Type数据格式，固定为 JSONapplication/json
X-YunDict-Event触发此次 Webhook 的事件类型project.created
X-YunDict-Signature(可选) HMAC-SHA256 签名，仅在设置 Secret 时存在d3b07384d113...

安全验证 (签名)

如果在配置 Webhook 时设置了 Secret，我们会使用该 Secret 对请求体（Payload）进行 HMAC-SHA256 签名，并将签名值放在 X-YunDict-Signature 头中。

验证步骤：

  1. 获取请求头中的 X-YunDict-Signature
  2. 使用您设置的 Secret 和接收到的原始请求体（JSON 字符串），计算 HMAC-SHA256 哈希值
  3. 将计算出的哈希值（hex 格式）与 X-YunDict-Signature 进行比对。如果一致，则请求来自云词

Node.js 示例代码：

const crypto = require('crypto');


function verifySignature(payload, secret, signature) {
  const hash = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');
  return hash === signature;
}

Python 示例代码：

import hmac
import hashlib
import json


def verify_signature(payload, secret, signature):
    hash_value = hmac.new(
        secret.encode(),
        json.dumps(payload).encode(),
        hashlib.sha256
    ).hexdigest()
    return hash_value == signature

数据格式 (Payload)

请求体是一个 JSON 对象，包含事件的详细信息。我们对所有事件的数据结构进行了统一标准化。

通用结构

{
  "event": "事件名称",
  "team": {
    "name": "team_identifier",
    "displayName": "My Team Name"
  },
  "project": {
    "name": "project_identifier",
    "displayName": "My Project Name"
  },
  "operator": {
    "name": "User Name",
    "email": "user@example.com",
    "image": "https://avatar.url..."
  }
  // ... 其他事件特定字段
}

字段说明：

  • event: 触发的事件名称（如 key.created, key.updated）
  • team: 事件所属的团队信息
  • project: 事件所属的项目信息
  • operator: (可选) 触发该事件的操作人信息
  • …: 其他字段取决于具体的事件类型（如 key 对象）

示例：文案创建事件

{
  "event": "key.created",
  "team": {
    "name": "my-team",
    "displayName": "My Awesome Team"
  },
  "project": {
    "name": "website-i18n",
    "displayName": "Website I18n Project"
  },
  "operator": {
    "name": "John Doe",
    "email": "john@example.com",
    "image": "https://..."
  },
  "key": {
    "id": 123,
    "name": "home.title",
    "tags": ["home", "header"]
  }
}

示例：文案更新事件

{
  "event": "key.updated",
  "team": {
    "name": "my-team",
    "displayName": "My Awesome Team"
  },
  "project": {
    "name": "website-i18n",
    "displayName": "Website I18n Project"
  },
  "operator": {
    "name": "Jane Smith",
    "email": "jane@example.com",
    "image": "https://..."
  },
  "key": {
    "id": 123,
    "name": "home.title",
    "tags": ["home", "header"]
  }
}

响应处理

您的服务器应在接收到请求后尽快返回 2xx 状态码（如 200 OK），以确认成功接收。

  • 如果在一定时间内未收到成功响应，或者返回 4xx/5xx 错误，我们会记录为发送失败
  • 建议您在接收到请求后先返回响应，再异步处理耗时的业务逻辑，避免请求超时

最佳实践：

// Express.js 示例
app.post('/webhook', async (req, res) => {
  // 1. 立即返回 200 响应
  res.status(200).send('OK');


  // 2. 异步处理 webhook 数据
  process.nextTick(() => {
    const { event, team, project, operator } = req.body;
    // 在这里处理您的业务逻辑
    handleWebhookEvent(req.body);
  });
});

配置 Webhook

您可以在项目设置中配置 Webhook：

  1. 进入项目的设置页面
  2. 找到 “Webhooks” 选项
  3. 点击 “添加 Webhook”
  4. 填写 Webhook URL 和可选的 Secret
  5. 选择要订阅的事件
  6. 保存配置

故障排查

Webhook 未收到请求

  • 检查 URL 是否可从公网访问
  • 确认防火墙规则允许来自云词的请求
  • 查看 Webhook 配置中的发送日志

签名验证失败

  • 确认使用的 Secret 与配置的一致
  • 检查是否使用原始请求体进行签名计算（不要解析后再序列化）
  • 确认签名算法为 HMAC-SHA256

请求超时

  • 确保您的服务器能在 5 秒内返回响应
  • 建议使用异步处理方式，先返回响应再处理业务逻辑