---
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)。