跳转到主要内容

​
v2 Webhooks API

​
概览

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

​
功能概览

级别价格webhook（回调接口）数量
自助式 Pro$5000/月1
Enterprise联系销售5+

​
支持 webhook 的产品

以下产品目前支持通过 webhook（回调接口）投递事件：

​
管理 Webhooks

Account Activity API 会在与订阅你服务的 X 账户相关的事件发生时，通过基于 webhook（回调接口）的 JSON 消息向你发送通知。X 会将这些活动推送到你注册的 webhook。按照以下步骤，你将学习如何管理 webhooks 和已订阅用户。 你将学习如何注册、查看和移除 webhooks 和已订阅用户。我们将使用简单的 cURL 命令向各个 API endpoint 发起请求。cURL 是一种使用 URL 语法来获取或发送请求的命令行工具。 在你的事件消费型应用开始接收 webhook 事件之前，有若干事项需要注意。如下所述，你需要创建一个 X App，获取 Account Activity API 访问权限，并开发一个用于消费 webhook 事件的 Web 应用。 

​
1. 开发 Webhook 消费方 App

要注册与您的 X App 关联的新 webhook，您需要开发、部署并托管一个用于接收 X webhook 事件并响应安全校验请求的 Web 应用。 在开始之前，建议先查看我们的示例应用\！
  • 创建一个具有公网可访问 HTTPS URL 的 Web 应用，该应用将充当 webhook endpoint 来接收事件。
  • 首先编写代码以接收来自 X 的 Challenge Response Check（CRC）GET 请求，并返回格式正确的 JSON 响应。
  • 注册您的 webhook URL。您需要向 /2/webhooks endpoint 发送一个 POST 请求，并在 JSON body 中包含该 URL。发出该请求后，X 会向您的 Web 应用发送 CRC 请求。
  • 当 webhook 注册成功时，响应会包含一个 webhook id。后续在调用支持 webhooks 的产品时需要该 webhook id。
  • X 会向您注册的 URL 发送包含事件的 POST 请求。这些事件将采用 JSON 编码。参见此处以查看示例 webhook JSON 载荷。

​
可选：使用 xurl 进行测试

为便于测试，xurl 工具现已支持临时 webhook（回调接口）！从 GitHub 安装 xurl project 的最新版本，配置授权后运行： 
xurl webhook start
这将生成一个临时的公共 webhook（回调接口）URL，自动处理所有 CRC 校验，并记录所有接收到的订阅事件。这是部署前验证设置的极佳方式。示例输出： 
正在使用 ngrok 启动 webhook（回调接口）服务器...
请输入您的 ngrok 认证令牌（留空则尝试使用 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 应用需要使用 App 的 consumer secret 对 CRC 校验进行加密。
  • 所有收到的私信都会通过 webhook（回调接口）投递。通过 POST /2/dm_conversations/with/:participant_id/messages 发送的所有私信也会通过 webhook（回调接口）投递。这样你的 Web 应用就能感知由其他客户端发送的私信。
  • 如果有多个 Web 应用共享同一个 webhook URL，且同一用户被映射到每个应用，则同一事件会多次发送到你的 webhook（每个 Web 应用各一次）。
  • 在某些情况下，你的 webhook 可能会收到重复事件。你的 webhook 应用应具备容错能力，并根据事件 id 进行去重。
  • 请参阅示例代码：

​
2. 保护 Webhook

X 的 webhook 型 API 提供两种方式来确认你的 webhook 服务器的安全性：
  1. 挑战-响应检查使 X 能够确认接收 webhook 事件的 Web 应用的所有权。
  2. 每个 POST 请求中的签名请求头使你能够确认传入的 webhook 来自 X。
有关实现要求，请参见 CRC 检查部分。

​
3. Webhooks API

webhook（回调接口）通过 Webhook Management API 进行管理。所有 endpoint 都需要使用 OAuth 2.0 App only Bearer Token 进行身份验证。 POST /2/webhooks 说明： 创建一个 webhook 配置。你可公开访问的 https 回调 URL 必须在 JSON 请求体中传递。
先为给定的应用程序 context 注册一个新的 webhook URL。 认证： OAuth2 App Only Bearer Token
  • Bearer token <BEARER_TOKEN> 例如 AAAAAAAAAAAA0%2EUifi76ZC9Ub0wn...
参数（JSON 请求体）： 
{
    "url": "<您的可公开访问的 https 回调 URL>"
}
  • URL <URL>，例如 https://yourdomain.com/webhooks/twitter/
Request： 根据需要完成以下更改后，将下面的 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 Bad Request） 失败将返回一个标准错误对象。 
{
    "errors": [
      {
        "message": "<Reason>: <Details>"
      }
    ],
    "title": "无效请求",
    "detail": "您的请求中有一个或多个参数无效。",
    "type": "https://api.twitter.com/2/problems/invalid-request"
}
常见失败原因包括：
原因说明
CrcValidationFailed回调 URL 未对 CRC 检查作出正确响应（例如超时、响应格式不正确）。
UrlValidationFailed提供的回调 URL 不满足要求（例如不是 https、格式无效）。
DuplicateUrlFailed你的应用已为该回调 URL 注册了一个 webhook（回调接口）。
WebhookLimitExceeded你的应用已达到允许的 webhook（回调接口）配置数量上限。
GET /2/webhooks 说明： 获取与你的应用（开发者账户）关联的所有 webhook 配置。 身份验证： OAuth2 App only 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（回调接口）配置的 List。若未配置任何 webhook（回调接口），则该 List 为空。 示例（已配置 1 个 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
  }
}
DELETE /2/webhooks/:webhook_id 描述： 使用特定的 webhook_id 删除 webhook 配置。该 ID 可从 POST /2/webhooks 的创建响应或 GET /2/webhooks 的列表响应中获取。 认证： OAuth 2.0 App only OAuth 2.0 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 未找到或未与您的 App 关联。
PUT /2/webhooks/:webhook_id 说明： 对指定 webhook 的 URL 触发挑战响应检查（CRC）。如果检查成功，返回 200，并将其状态设置为 valid 以重新启用该 webhook。 认证： OAuth 2.0 App only Bearer Token
  • Bearer token <BEARER_TOKEN> 例如 AAAAAAAAAAAA0%2EUifi76ZC9Ub0wn...
路径参数：
参数说明
webhook_id要验证的 webhook 的 id。
请求： 运行以下命令，根据所提供 App 的配置验证该 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 未找到，或未与您的 App 关联。
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 作为消息
  • 使用 App 的 consumer secret 作为密钥
  • 生成 HMAC SHA-256 hash
  • 将结果进行 Base64 编码

​
示例 App

⌘I