メインコンテンツへスキップ

​
v2 Webhooks API

​
概要

v2 Webhooks API は、webhook ベースの JSON メッセージを通じて、X アカウントからのリアルタイムなイベント通知を受信できるようにします。これらの API により、webhook の登録と管理、イベントを処理するコンシューマー向けアプリケーションの開発、CRC（チャレンジ・レスポンス・チェック）および署名ヘッダーによる安全な通信の確保が可能になります。

​
機能サマリー

ティア料金webhook 数
Self-Serve Pro$5,000/月1
Enterprise営業担当にお問い合わせ5以上

​
Webhook をサポートする製品

現在、Webhook を介したイベント配信に対応している製品は次のとおりです。

​
Webhook を管理する

Account Activity API は、あなたのサービスに購読されている X アカウントでイベントが発生するたびに、webhook 経由の JSON メッセージを提供します。X はそれらのアクティビティを、登録済みの webhook に配信します。以下の手順では、webhook と購読中のユーザーの管理方法を説明します。 webhook と購読中のユーザーについて、登録・確認・削除の方法を扱います。各種 API endpoint にリクエストを送るために、簡単な cURL コマンドを使用します。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 を登録します。JSON ボディに URL を含めて /2/webhooks endpoint に POST リクエストを送信します。このリクエストを行うと、X はあなたの Web アプリに CRC リクエストを送信します。
  • webhook が正常に登録されると、レスポンスには webhook の id が含まれます。この webhook id は、webhook をサポートするプロダクトにリクエストを行う際に後で必要になります。 
  • X は、登録した URL にイベントを含む POST リクエストを送信します。これらのイベントは JSON でエンコードされます。webhook の JSON ペイロード例はこちらをご覧ください。

​
任意: テストに xurl を使用する

テスト用途として、xurl ツールは一時的な webhook に対応しました。GitHub から最新バージョンのxurl Projectをインストールし、認可設定を行ったうえで、次を実行してください: 
xurl webhook start
これにより、一時的な公開 webhook URL が生成され、CRC チェックが自動的に処理され、受信した購読イベントがすべて記録されます。デプロイ前にセットアップを検証するのに最適な方法です。出力例： 
ngrokでwebhookサーバーを開始しています...
ngrok authtokenを入力してください（空欄の場合はNGROK_AUTHTOKEN環境変数を試行します）：

ngrok認証にNGROK_AUTHTOKEN環境変数を使用しようとしています。
ローカルポート8080に転送するようngrokを設定しています
Ngrokトンネルが確立されました！
  転送URL: https://<your-ngrok-subdomain>.ngrok-free.app -> localhost:8080

X API webhook登録にはこのURLを使用してください: https://<your-ngrok-subdomain>.ngrok-free.app/webhook

ngrokトンネルからのリクエストを処理するローカルHTTPサーバーを開始しています（https://<your-ngrok-subdomain>.ngrok-free.appから転送）...
重要な注意事項
  • webhook の URL を登録する際は、CRC チェックの暗号化に App の consumer secret を使用する必要があります。
  • 受信したダイレクトメッセージはすべて webhook 経由で配信されます。 POST /2/dm_conversations/with/:participant_id/messages で送信されたダイレクトメッセージもすべて webhook 経由で配信されます。これは、別のクライアントから送信されたダイレクトメッセージも Web アプリが把握できるようにするためです。
  • 同じ webhook URL を共有する複数の Web アプリがあり、同じユーザーが各 App にマッピングされている場合、同じイベントが複数回（Web アプリごとに 1 回）webhook に送信されます。
  • 場合によっては、webhook が重複イベントを受信することがあります。webhook アプリはこれに耐性を持ち、イベント ID によって重複排除を行う必要があります。
  • サンプルコード:

​
2. Webhook のセキュリティ保護

X の webhook ベースの API では、webhook サーバーのセキュリティを確認するために次の 2 つの方法を提供しています。
  1. チャレンジレスポンス検証により、webhook イベントを受信する Web アプリの所有権を X が確認できます。
  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 ボディで渡す必要があります。
まず、指定された application 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": "<your callback url>",
    "valid": true,
    "created_at": "YYYY-mm-DDTHH:MM:ss.000Z"
  }
}
失敗（400 Bad Request） 失敗時には標準的なエラーオブジェクトが返されます。 
{
    "errors": [
      {
        "message": "<理由>: <詳細>"
      }
    ],
    "title": "無効なリクエスト",
    "detail": "リクエストの1つ以上のパラメータが無効です。",
    "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 の構成一覧を返します。webhook が構成されていない場合は、一覧は空になります。 例（webhook が 1 件構成されている場合）: 
{
  "data": [
    {
      "created_at": "YYYY-mm-DDTHH:MM:ss.000Z",
      "id": "<webhook_id>",
      "url": "<コールバック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 の一覧レスポンスから取得できます。 認証: OAuth2 App only Bearer Token
  • Bearer token <BEARER_TOKEN> 例: AAAAAAAAAAAA0%2EUifi76ZC9Ub0wn...
パスパラメータ:
ParameterDescription
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) 削除に成功した場合、“deleted” ステータスが true の JSON レスポンスを返します。 例（webhook の削除が成功した場合）: 
{
  "data": {
    "deleted": true
  }
}
失敗 (400 Bad Request)
理由説明
WebhookIdInvalid指定された webhook_id が見つからない、またはお客様の App に関連付けられていません。
PUT /2/webhooks/:webhook_id 説明: 指定された webhook の URL に対して Challenge Response Check (CRC) を実行します。チェックが成功すると、ステータスを valid に設定して webhook を再有効化し、200 を返します。 認証: OAuth2 App only Bearer Token
  • Bearer token <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 が見つからないか、あなたの App に関連付けられていません。
CrcValidationFailedコールバックURLがCRCチェックリクエストに正しく応答しませんでした。

​
4. CRC チェック

Challenge Response Check（CRC）は、提供したコールバック URL が有効であり、かつそのコールバック URL をあなたが制御していることを X が検証するための仕組みです。 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 のコンシューマーシークレットを使用する
  • HMAC-SHA-256 の hash を生成する
  • 結果を Base64 でエンコードする

​
サンプル App

  • Simple webhook server
    • CRC チェックに応答し、POST イベントを受け付ける方法を示す単一の Python スクリプト。
  • Account Activity API sample dashboard
    • bun.sh で作成された Web アプリで、webhook とサブスクリプションを管理し、App 内でライブイベントを直接受信できます。
⌘I