117 lines
3.8 KiB
Plaintext
117 lines
3.8 KiB
Plaintext
---
|
||
title: Webhooks
|
||
description: 当您的 CRM 中发生事件时接收实时通知。
|
||
---
|
||
|
||
import { VimeoEmbed } from '/snippets/vimeo-embed.mdx';
|
||
|
||
当 Twenty 中发生事件时，Webhook 会实时将数据推送到您的系统 — 无需轮询。 使用它们来保持外部系统同步、触发自动化或发送警报。
|
||
|
||
## 创建 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)。
|