当 Twenty 中发生事件时，Webhook 会实时将数据推送到您的系统 — 无需轮询。 使用它们来保持外部系统同步、触发自动化或发送警报。
创建 Webhook
- 前往 设置 → APIs & Webhooks → Webhooks
- 单击 + 创建 Webhook
- 输入您的 Webhook URL（必须可公开访问）
- 单击 保存
Webhook 会立即激活并开始发送通知。
管理 Webhooks
编辑：点击该 Webhook → 更新 URL → 保存
删除：点击该 Webhook → 删除 → 确认
Twenty 会针对以下事件类型发送 Webhook：
| 事件 | 示例 |
|---|
| 记录已创建 | person.created, company.created, note.created |
| 记录已更新 | person.updated, company.updated, opportunity.updated |
| 记录已删除 | person.deleted, company.deleted |
负载格式
每个 Webhook 都会发送一个带有 JSON 正文的 HTTP POST：
{
"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"
}
| 字段 | 描述 |
|---|
事件 | 发生了什么（例如，person.created） |
数据 | 已创建/更新/删除的完整记录 |
时间戳 | 事件发生的时间（UTC） |
请返回 2xx HTTP 状态（200-299）以确认已接收。 非 2xx 的响应将被记录为投递失败。
Webhook 验证
为了安全起见，Twenty 会对每个 Webhook 请求进行签名。 请验证签名以确保请求真实有效。
| 标题 | 描述 |
|---|
X-Twenty-Webhook-Signature | HMAC SHA256 签名 |
X-Twenty-Webhook-Timestamp | 请求时间戳 |
验证步骤
- 从
X-Twenty-Webhook-Timestamp 获取时间戳
- 构造字符串：
{timestamp}:{JSON payload}
- 使用您的 Webhook 密钥计算 HMAC SHA256
- 与
X-Twenty-Webhook-Signature 进行比较
示例（Node.js）
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 isValid = expectedSignature === req.headers["x-twenty-webhook-signature"];
Webhooks 与工作流
| 方法 | 方向 | 用例 |
|---|
| Webhooks | OUT | 自动通知外部系统任何记录变更 |
| 工作流 + HTTP 请求 | OUT | 使用自定义逻辑（过滤、转换）向外发送数据 |
| 工作流 Webhook 触发器 | IN | 从外部系统接收数据到 Twenty |
