V2 Webhooks API

概要

V2 Webhooks API は、webhook ベースの JSON メッセージを介して、X アカウントからのリアルタイムなイベント通知を受信できるようにするものです。これらの API を使用すると、webhook の登録と管理、イベントを処理するコンシューマー向けアプリの開発、さらに CRC（challenge-response check）と署名ヘッダーによる安全な通信の確保が可能になります。

機能概要

ティア	料金	Webhook 数
セルフサービスプロ	$5,000/月	1
エンタープライズ	営業にお問い合わせ	5件以上

Webhook をサポートする製品

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

Webhook を管理する

Account Activity API は、あなたのサービスに登録された X アカウントに関連するイベントが発生するたびに、webhook 経由の JSON メッセージを提供します。X はそれらのアクティビティを、あなたが登録した webhook に配信します。以下の手順では、webhook と購読ユーザーの管理方法を説明します。 webhook および購読ユーザーについて、登録、表示、削除の方法を学びます。各種 API エンドポイントへのリクエストには、シンプルな cURL コマンドを使用します。cURL は、URL 構文を用いてリクエストを送受信するためのコマンドラインツールです。イベントコンシューマーアプリケーションで webhook イベントの受信を開始する前に、いくつか注意すべき点があります。以下のとおり、X のアプリを作成し、Account Activity API へのアクセスを取得し、webhook イベントを処理する Web アプリを開発する必要があります。

1. Webhook コンシューマーアプリを開発する

X のアプリに関連付けられた新規 webhook を登録するには、X の webhook イベントを受信し、当社のセキュリティリクエストに応答できる Web アプリを開発・デプロイ・ホストする必要があります。 開始前に、サンプルアプリをご確認いただくことをおすすめします。

イベントを受け取る webhook エンドポイントとして機能する、外部からアクセス可能な HTTPS URL を持つ Web アプリを作成します。
- 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 を登録します。JSON ボディに URL を含めて /2/webhooks エンドポイントに POST リクエストを送信します。このリクエストを行うと、X は CRC リクエストをあなたの Web アプリに送信します。
webhook が正常に登録されると、レスポンスに webhook の id が含まれます。この webhook id は、webhook をサポートするプロダクトに対してリクエストを行う際に後で必要になります。
X は、登録した URL にイベントを含む POST リクエストを送信します。これらのイベントは JSON でエンコードされています。webhook の JSON ペイロード例はこちらをご覧ください。

任意: テストには xurl を使用

テスト用に、xurl ツールで一時的な webhook がサポートされました。GitHub から xurl プロジェクトの最新バージョンをインストールし、認可設定を行ったうえで、次を実行してください:

xurl webhook start

これは一時的な公開Webhook URLを生成し、CRCチェックを自動処理し、受信したサブスクリプションイベントをすべてログに記録します。デプロイ前にセットアップを確認するのに最適です。出力例：

ngrokでwebhookサーバーを起動中...
ngrokのauthtokenを入力してください（空欄の場合、NGROK_AUTHTOKEN環境変数を使用します）:

ngrok認証にNGROK_AUTHTOKEN環境変数を使用します。
ngrokをローカルポート8080へ転送するよう設定中
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 チェックの暗号化にアプリの consumer secret を使用する必要があります。
すべての受信ダイレクトメッセージは webhook 経由で配信されます。 POST /2/dm_conversations/with/:participant_id/messages で送信されたダイレクトメッセージも webhook 経由で配信されます。これは、別クライアントから送信されたダイレクトメッセージもウェブアプリで把握できるようにするためです。
同じ webhook URL を共有する複数のウェブアプリがあり、同一ユーザーが各アプリに対応付けられている場合、同じイベントが（ウェブアプリごとに1回ずつ）複数回あなたの webhook に送信されます。
場合によっては、webhook が重複イベントを受信することがあります。webhook アプリはこれに耐性を持ち、event ID で重複排除を行ってください。
サンプルコード:
- Account Activity API Setup — Account Activity API のエンタープライズ層を使用し、webhook イベントを表示する Node ウェブアプリ。

2. Webhook のセキュリティ確保

X の Webhook ベースの API では、Webhook サーバーのセキュリティを検証するために次の 2 つの方法を提供しています：

チャレンジレスポンス検証により、Webhook イベントを受信する Web アプリの所有権を X が確認します。
各 POST リクエストの署名ヘッダーにより、受信した Webhook が X から送信されたものであることを検証できます。

実装要件については、CRC Check セクションを参照してください。

3. Webhooks API

Webhooks は Webhook Management API で管理します。すべてのエンドポイントで OAuth2 App Only Bearer Token による認証が必要です。

Webhook の追加

POST /2/webhooks 説明: Webhook 構成を作成します。インターネットからアクセス可能な https コールバック URL を JSON ボディで指定する必要があります。
まずは、指定されたアプリケーションコンテキストに対して新しい webhook URL を登録します。 認証: OAuth2 App Only Bearer Token

Bearer token <BEARER_TOKEN> 例: AAAAAAAAAAAA0%2EUifi76ZC9Ub0wn...

パラメータ (JSON Body):

{
    "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": "<your callback url>",
    "valid": true,
    "created_at": "YYYY-mm-DDTHH:MM:ss.000Z"
  }
}

失敗（400 Bad Request） 失敗時には標準のエラーオブジェクトが返されます。

{
    "errors": [
      {
        "message": "<Reason>: <Details>"
      }
    ],
    "title": "無効なリクエスト",
    "detail": "リクエストに含まれる1つ以上のパラメータが無効です。",
    "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 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": "<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 App Only 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) 削除に成功すると、“deleted” ステータスが true の JSON レスポンスを返します。 例（Webhook の削除が成功した場合）：

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

失敗 (400 Bad Request)

理由	説明
`WebhookIdInvalid`	指定された `webhook_id` が見つからないか、アプリに関連付けられていません。

Webhook を検証して再有効化する

PUT /2/webhooks/:webhook_id 説明: 指定された webhook の URL に対して CRC（Challenge Response Check）を実行します。チェックが成功すると、ステータスを valid に設定して webhook を再有効化し、HTTP 200 を返します。 認証: 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）は、提供されたコールバック 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エンコードされたhmacハッシュ>"
}

レスポンスの生成方法:

メッセージに crc_token を使用する
キーにアプリのconsumer secretを使用する
HMAC-SHA256 のハッシュを作成する
結果を Base64 でエンコードする

サンプルアプリ

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

概要

ポスト

ユーザー

ダイレクトメッセージ

いいね

リスト

スペース

コミュニティ

コミュニティノート

トレンド

メディア

Xのアクティビティ

利用方法

ストリーム接続

法令遵守

エンタープライズ v2

いいねストリーム

GNIP 2.0

Introduction

V2 Webhooks API

概要

機能概要

Webhook をサポートする製品

Webhook を管理する

1. Webhook コンシューマーアプリを開発する

任意: テストには xurl を使用

2. Webhook のセキュリティ確保

3. Webhooks API

Webhook の追加

Webhook の表示

Webhook の削除

Webhook を検証して再有効化する

4. CRC チェック

サンプルアプリ

概要

ポスト

ユーザー

ダイレクトメッセージ

いいね

リスト

スペース

コミュニティ

コミュニティノート

トレンド

メディア

Xのアクティビティ

利用方法

ストリーム接続

法令遵守

エンタープライズ v2

いいねストリーム

GNIP 2.0

​V2 Webhooks API

​概要

​機能概要

​Webhook をサポートする製品

​Webhook を管理する

​1. Webhook コンシューマーアプリを開発する

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

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

​3. Webhooks API

​Webhook の追加

​Webhook の表示

​Webhook の削除

​Webhook を検証して再有効化する

​4. CRC チェック

​サンプルアプリ

V2 Webhooks API

概要

機能概要

Webhook をサポートする製品

Webhook を管理する

1. Webhook コンシューマーアプリを開発する

任意: テストには xurl を使用

2. Webhook のセキュリティ確保

3. Webhooks API

Webhook の追加

Webhook の表示

Webhook の削除

Webhook を検証して再有効化する

4. CRC チェック

サンプルアプリ