Introduction

​

V2 Webhooks API

​

概览

V2 Webhooks API 使开发者能够通过基于 webhook 的 JSON 消息，从 X 账户接收实时事件通知。这些 API 支持你注册和管理 webhook，开发用于处理事件的应用，并通过质询-响应检查（CRC）和签名请求头确保通信安全。

​

功能摘要

等级	价格	Webhook 数量
自助 免费	$5000/月	1
企业版	联系销售	5+

​

支持 Webhook 的产品

以下产品目前支持通过 Webhook 传递事件：

• Account Activity API（AAA）
• Filtered Stream

​

管理 Webhook

Account Activity API 会在与订阅你服务的 X 账户相关的事件发生时，通过 webhook 向你提供 JSON 消息。X 会将这些活动发送到你注册的 webhook。接下来你将了解如何管理 webhooks 和已订阅用户。

你将学习如何注册、查看和移除 webhooks 以及已订阅用户。我们将使用简单的 cURL 命令向各个 API 端点发起请求。cURL 是一款使用 URL 语法发送或接收请求的命令行工具。

在你的事件消费型应用开始接收 webhook 事件之前，还有若干事项需要准备。如下所述，你需要创建一个 X 应用、获取 Account Activity API 的访问权限，并开发一个用于接收和处理 webhook 事件的 Web 应用。 

​

1. 开发 Webhook 消费者应用

要注册与你的 X 应用关联的新 webhook，你需要开发、部署并托管一个用于接收 X webhook 事件并响应我们安全校验请求的 Web 应用。

在开始之前，我们建议先查看我们的示例应用\！

• 创建一个具有公网可访问 HTTPS URL 的 Web 应用，将其作为接收事件的 webhook 终端（endpoint）。
  • URI 的路径可自行决定。以下示例有效：https://mydomain.com/service/listen
  • 如果你要同时监听来自多种来源的 webhook，常见的模式是：https://mydomain.com/webhook/twitter
  • 注意，指定的 URL 不能包含端口（https://mydomain.com:5000/NoWorkie）。
• 首先编写代码以接收 X 的 Challenge Response Check（CRC）GET 请求，并返回格式正确的 JSON 响应。
• 注册你的 webhook URL。你需要向 /2/webhooks 端点发起一个 POST 请求，在 JSON 正文中包含该 URL。发起此请求后，X 会向你的 Web 应用发送 CRC 请求。
• 当 webhook 注册成功后，响应会包含一个 webhook id。稍后在对支持 webhook 的产品发起请求时需要用到该 webhook id。
• X 会向你注册的 URL 发送包含事件的 POST 请求。这些事件将以 JSON 编码。示例 webhook JSON 负载见此处。

​

可选：使用 xurl 进行测试

用于测试时，xurl 工具现已支持临时 webhook！从 GitHub 安装 xurl 项目 的最新版本，配置授权后运行：

xurl webhook start

这将生成一个临时的公开 webhook URL，自动处理所有 CRC 校验，并记录所有收到的订阅事件。这是在部署前验证设置的绝佳方式。示例输出：

正在使用 ngrok 启动 webhook 服务器…
请输入你的 ngrok authtoken（留空将尝试使用 NGROK_AUTHTOKEN 环境变量）：

正在尝试使用 NGROK_AUTHTOKEN 环境变量进行 ngrok 认证。
正在配置 ngrok 转发到本地端口：8080
已建立 ngrok 隧道！
  转发 URL：https://<your-ngrok-subdomain>.ngrok-free.app -> localhost:8080

使用此 URL 注册 X API 的 webhook：https://<your-ngrok-subdomain>.ngrok-free.app/webhook

正在启动本地 HTTP 服务器，以处理来自 ngrok 隧道的请求（由 https://<your-ngrok-subdomain>.ngrok-free.app 转发）…

重要说明

• 在注册 webhook URL 时，你的 Web 应用需要使用应用的 consumer secret 对 CRC 检查进行加密。

• 所有收到的私信都会通过 webhook 送达。通过 POST /2/dm_conversations/with/:participant_id/messages 发送的所有私信也会通过 webhook 送达。这样你的 Web 应用才能获知由其他客户端发送的私信。

• 如果你有多个 Web 应用共享同一个 webhook URL，且同一用户映射到每个应用，那么同一事件会被多次发送到你的 webhook（每个 Web 应用一次）。

• 在某些情况下，你的 webhook 可能会接收到重复事件。你的 webhook 应用应具备容错能力，并根据事件 ID 去重。

• 参见示例代码：

  • Account Activity API Setup，一个使用 Account Activity API 企业版来显示 webhook 事件的 Node Web 应用。

​

2. Webhook 安全性

X 的 webhook 型 API 提供两种方法来验证你的 webhook 服务器的安全性：

1. 挑战—响应校验使 X 能够确认接收 webhook 事件的 Web 应用的所有权。
2. 每个 POST 请求中的签名标头使你能够确认传入的 webhook 确实来自 X。

有关实现要求，请参见 CRC 检查部分。

​

3. Webhooks API

Webhooks 通过 Webhook Management API 进行管理。所有端点均需使用 OAuth2 App Only Bearer Token 进行认证。

​

添加 webhook

POST /2/webhooks

描述：

创建 webhook 配置。你公开可访问的 https 回调 URL 必须在 JSON 正文中传递。
先为指定的应用上下文注册一个新的 webhook URL。

认证：

OAuth2 仅应用 Bearer Token

• Bearer token <BEARER_TOKEN> 例如 AAAAAAAAAAAA0%2EUifi76ZC9Ub0wn...

参数（JSON 正文）：

{
    "url": "<您可公开访问的 HTTPS 回调 URL>"
}

• URL <URL> 例如 https://yourdomain.com/webhooks/twitter/

请求： 按需修改后，将以下 cURL 请求复制到你的命令行中：

  ```
  curl --request POST --url 'https://api.twitter.com/2/webhooks?url=<URL>' --header 'authorization: Bearer <BEARER_TOKEN>'
  --data '{
"url": "https://yourdomain.com/webhooks/twitter"
          }'
  ```

响应：

成功（200 OK）

成功的响应表示已创建 webhook，且初始 CRC 检查已通过。

{
  "data": {
    "id": "<webhook_id>",
    "url": "<你的回调 URL>",
    "valid": true,
    "created_at": "YYYY-mm-DDTHH:MM:ss.000Z"
  }
}

失败（400 错误请求）

失败时会返回标准错误对象。

{
    "errors": [
      {
        "message": "<原因>: <详情>"
      }
    ],
    "title": "无效请求",
    "detail": "你的请求中存在一个或多个无效参数。",
    "type": "https://api.twitter.com/2/problems/invalid-request"
}

常见失败原因包括：

原因	描述
CrcValidationFailed	回调 URL 未对 CRC 检查做出正确响应（例如超时或返回内容不正确）。
UrlValidationFailed	提供的回调 URL 不符合要求（例如非 https，或格式无效）。
DuplicateUrlFailed	你的应用已为该回调 URL 注册了一个 webhook。
WebhookLimitExceeded	你的应用已达到允许的 webhook 配置数量上限。

​

查看 webhook

GET /2/webhooks

**说明：**检索与你的应用（开发者账户）关联的所有 webhook 配置。

认证：

OAuth2 应用仅限 Bearer Token

• Bearer token <BEARER_TOKEN>，例如 AAAAAAAAAAAA0%2EUifi76ZC9Ub0wn...

• URL <URL>，例如 https://yourdomain.com/webhooks/twitter/

**请求：**运行以下命令以检索给定应用已注册的所有 webhook URL 及其状态。

在完成以下修改后，将下面的 cURL 请求复制到你的命令行中：

  ```
  curl --request GET --url 'https://api.twitter.com/2/webhooks' --header 'authorization: Bearer <BEARER_TOKEN>'
  ```

成功（200 OK）

返回 webhook 配置列表。若未配置任何 webhook，则列表为空。

示例（配置了一个 webhook 的情况）：

{
  "data": [
    {
      "created_at": "YYYY-mm-DDTHH:MM:ss.000Z",
      "id": "<webhook_id>",
      "url": "<callback url>",
      "valid": true
    }
  ],
  "meta": {
    "result_count": 1
  }
}

示例（未配置 Webhook）：

{
  "data": [],
  "meta": {
    "result_count": 0
  }
}

​

移除 webhook

DELETE /2/webhooks/:webhook_id

说明： 使用指定的 webhook_id 删除 webhook 配置。该 ID 可从 POST /2/webhooks 的创建响应或 GET /2/webhooks 的列表响应中获取。

认证：

OAuth2 应用仅限 Bearer Token

• Bearer token <BEARER_TOKEN> 例如 AAAAAAAAAAAA0%2EUifi76ZC9Ub0wn...

路径参数：

参数	说明
webhook_id	要删除的 webhook 的 ID。

请求： 运行以下命令，从所提供的应用配置中移除该 webhook。

完成相应修改后，将下面的 cURL 请求复制到你的命令行中：

  ```
  curl --request DELETE --url 'https://api.twitter.com/2/webhooks/:WEBHOOK_ID' --header 'authorization: Bearer <BEARER_TOKEN>'
  ```

  **响应：**

成功（200 OK）

删除成功时，返回一个 JSON 响应，其中 “deleted” 状态为 true。

示例（成功删除 webhook）：

{
  "data": {
    "deleted": true
  }
}

失败（400 错误的请求）

原因	说明
WebhookIdInvalid	未找到提供的 webhook_id，或其未与您的应用关联。

​

验证并重新启用 webhook

PUT /2/webhooks/:webhook_id

描述： 对指定 webhook 的 URL 触发挑战-响应检查（CRC）。如果检查通过，将返回 200，并通过将其状态设置为 valid 来重新启用该 webhook。

认证：

OAuth2 应用专用 Bearer 令牌

• Bearer 令牌 <BEARER_TOKEN>，例如 AAAAAAAAAAAA0%2EUifi76ZC9Ub0wn...

路径参数：

参数	描述
webhook_id	要验证的 webhook 的 id。

请求： 运行以下命令，以使用所提供应用的配置验证该 webhook。

完成以下更改后，将下面的 cURL 请求复制到命令行中：

  ```
  curl --request PUT --url 'https://api.twitter.com/2/webhooks/:WEBHOOK_ID' --header 'authorization: Bearer <BEARER_TOKEN>'
  ```

  **响应：**

成功（200 OK）

200 OK 响应表示已发起 CRC 检查请求，但并不保证 CRC 检查已通过。响应中的 valid 字段反映的是检查尝试之后的状态。若 CRC 检查成功，webhook 的状态将更新为 valid。你可以使用 GET /2/webhooks 查看当前状态。

{
  "data": {
    "valid": true // 表示 CRC 校验尝试完成后的状态
  }
}

失败（400 Bad Request）

原因	说明
WebhookIdInvalid	提供的 webhook_id 未找到，或未与您的应用关联。
CrcValidationFailed	回调 URL 未对 CRC 校验请求作出正确响应。

​

4. CRC 检查

Challenge Response Check（CRC，挑战–响应校验）是 X 用于验证你提供的回调 URL 是否有效并确认你对其拥有控制权的机制。

CRC 触发时机：

• 初次注册 webhook（POST /2/webhooks）
• 由 X 每小时进行一次校验
• 通过 PUT /2/webhooks/:id 手动触发

示例：

GET https://your-webhook-url.com/webhook?crc_token=challenge_string

示例 JSON 响应体：

{
  "response_token": "sha256=<base64_encoded_hmac_hash>"
}

如何构建响应：

• 使用 crc_token 作为消息
• 使用应用的**consumer secret（消费者密钥）**作为密钥
• 生成 HMAC-SHA256 哈希
• 将结果进行 Base64 编码

​

示例应用

• Simple webhook server
  • 一个单文件的 Python 脚本，演示如何响应 CRC 检查并接收 POST 事件。
• Account Activity API 示例控制台
  • 使用 bun.sh 构建的 Web 应用，可直接在应用内管理 webhook、订阅，并接收实时事件。