snapshot of https://github.com/twentyhq/twenty.git (main, 2026-09-17; blobs > 131072B omitted)

packages/twenty-docs/l/zh/developers/extend/webhooks.mdx

@@ -0,0 +1,117 @@
+---
+title: Webhooks
+icon: satellite-dish
+description: 当记录更改时收到通知 — 在每次创建、更新或删除时向您的端点发送 HTTP POST。
+---
+
+import { VimeoEmbed } from '/snippets/vimeo-embed.mdx';
+
+每当记录被创建、更新或删除时，Twenty 会向您的 URL 发送 HTTP POST。 涵盖所有对象类型，包括自定义对象。
+
+## 创建 Webhook
+
+1. 前往 **设置 → APIs & Webhooks → Webhooks**
+2. 单击 **+ 创建 Webhook**
+3. 输入您的 Webhook URL（必须可公开访问）
+4. 单击 **保存**
+
+Webhook 会立即激活并开始发送通知。
+
+<VimeoEmbed videoId="928786708" title="创建 Webhook" />
+
+### 管理 Webhooks
+
+**编辑**：点击该 Webhook → 更新 URL → **保存**
+
+**删除**：点击该 Webhook → **删除** → 确认
+
+## 事件
+
+Twenty 会针对以下事件类型发送 Webhook：
+
+| 事件        | 示例                                                         |
+| --------- | ---------------------------------------------------------- |
+| **记录已创建** | `person.created`, `company.created`, `note.created`        |
+| **记录已更新** | `person.updated`, `company.updated`, `opportunity.updated` |
+| **记录已删除** | `person.deleted`, `company.deleted`                        |
+
+所有事件类型都会发送到您的 Webhook URL。 事件过滤可能会在未来的版本中添加。
+
+## 负载格式
+
+每个 Webhook 都会发送一个带有 JSON 正文的 HTTP POST：
+
+```json
+{
+  "event": "person.created",
+  "data": {
+    "id": "abc12345",
+    "firstName": "Alice",
+    "lastName": "Doe",
+    "email": "alice@example.com",
+    "createdAt": "2025-02-10T15:30:45Z",
+    "createdBy": "user_123"
+  },
+  "timestamp": "2025-02-10T15:30:50Z"
+}
+```
+
+| 字段          | 描述                         |
+| ----------- | -------------------------- |
+| `event`     | 发生了什么（例如，`person.created`） |
+| `data`      | 已创建/更新/删除的完整记录             |
+| `timestamp` | 事件发生的时间（UTC）               |
+
+<Note>
+请返回 **2xx HTTP 状态**（200-299）以确认已接收。 非 2xx 的响应将被记录为投递失败。
+</Note>
+
+## Webhook 验证
+
+为了安全起见，Twenty 会对每个 Webhook 请求进行签名。 请验证签名以确保请求真实有效。
+
+### 请求头
+
+| 请求头                          | 描述             |
+| ---------------------------- | -------------- |
+| `X-Twenty-Webhook-Signature` | HMAC SHA256 签名 |
+| `X-Twenty-Webhook-Timestamp` | 请求时间戳          |
+
+### 验证步骤
+
+1. 从 `X-Twenty-Webhook-Timestamp` 获取时间戳
+2. 构造字符串：`{timestamp}:{JSON payload}`
+3. 使用您的 Webhook 密钥计算 HMAC SHA256
+4. 与 `X-Twenty-Webhook-Signature` 进行比较
+
+### 示例（Node.js）
+
+```javascript
+const crypto = require("crypto");
+
+const timestamp = req.headers["x-twenty-webhook-timestamp"];
+const payload = JSON.stringify(req.body);
+const secret = "your-webhook-secret";
+
+const stringToSign = `${timestamp}:${payload}`;
+const expectedSignature = crypto
+  .createHmac("sha256", secret)
+  .update(stringToSign)
+  .digest("hex");
+
+const receivedSignature = req.headers["x-twenty-webhook-signature"];
+const isValid = crypto.timingSafeEqual(
+  Buffer.from(expectedSignature, "hex"),
+  Buffer.from(receivedSignature, "hex")
+);
+```
+
+## Webhooks 与工作流
+
+| 方法                  | 方向  | 用例                   |
+| ------------------- | --- | -------------------- |
+| **Webhooks**        | OUT | 自动通知外部系统任何记录变更       |
+| **工作流 + HTTP 请求**   | OUT | 使用自定义逻辑（过滤、转换）向外发送数据 |
+| **工作流 Webhook 触发器** | IN  | 从外部系统接收数据到 Twenty    |
+
+如需接收外部数据，请参见 [设置 Webhook 触发器](/l/zh/user-guide/workflows/how-tos/connect-to-other-tools/set-up-a-webhook-trigger)。