Skip to main content
The V2 Webhooks API enables developers to receive real-time event notifications from X accounts via webhook-based JSON messages. These APIs allow you to register and manage webhooks, develop consumer applications to process events, and ensure secure communication through challenge-response checks (CRC) and signature headers.

​
Overview

Real-time delivery

Receive events instantly as they occur

Push-based

Data sent directly to your server — no polling

Secure

CRC validation and signature verification

Reliable

Retry and recovery support

​
Products that support webhooks

These are the products that currently support delivering events via webhook:

​
How webhooks work

  1. Event occurs — A user posts, sends a DM, gets followed, etc.
  2. X sends a POST request — JSON event payload sent to your registered webhook URL
  3. You process the event — Your server handles the event data
  4. Respond with 200 OK — Return a 200 status to acknowledge receipt

​
Webhook requirements

​
Endpoints

All endpoints require OAuth2 App Only Bearer Token authentication.

​
Security

X’s webhook-based APIs provide two methods for confirming the security of your webhook server:
  1. Challenge-Response Check (CRC) — X sends periodic GET requests to your webhook URL. You respond with an HMAC-SHA256 hash to prove you control the endpoint. CRC checks happen on initial registration, hourly, and on manual re-validation.
  2. Signature verification — Each POST request from X includes a signature header. You can verify this signature to confirm X is the source of incoming events.

​
Signature headers

X sends one of two signature headers on each webhook POST. Both use the format sha256=<base64_encoded_hmac_sha256> and are calculated over the raw request body.
  • Apps that only have an OAuth 2.0 client secret configured receive only X-Twitter-Webhooks-Signature-OAuth2.
  • Apps that have both an OAuth 2.0 client secret and an OAuth 1.0 consumer secret may receive both headers during migration. Verify X-Twitter-Webhooks-Signature-OAuth2 and, if you still need to support the legacy path, fall back to X-Twitter-Webhooks-Signature.
  • Apps that only have an OAuth 1.0 consumer secret continue to receive X-Twitter-Webhooks-Signature unchanged.
The same rules apply to the CRC response_token: generate it with the OAuth 2.0 client secret when available, or with the OAuth 1.0 consumer secret for existing OAuth 1.0-only integrations.
The OAuth 2.0 App Only Bearer Token used in the Authorization header when calling /2/webhooks is not used to compute CRC responses or webhook signatures. CRC and signature verification always use the app’s OAuth 2.0 client secret or OAuth 1.0 consumer secret. Keep client and consumer secrets server-side, and never include them in webhook registration requests.

See full implementation details

Step-by-step CRC setup, code examples, and signature verification

​
Webhook validation

A CRC check is sent to your webhook in the following cases:
  • Immediately upon creation
  • On an explicit PUT request (PUT /2/webhooks/{id})
  • Periodically every 30 minutes, but only if the webhook has not been successfully validated in the past 24 hours
A webhook is marked as invalid when:
  • It returns an invalid response to a CRC check
    • Returns a 2XX status code but the response_token is incorrect
    • Returns a 3XX status code
    • Results in an SSL exception
  • It experiences persistent transient errors such that it has not successfully validated for more than 28 hours (includes a 4-hour grace period for transient issues)
    • The following responses are treated as transient errors:
      • 4XX status code
      • 5XX status code
      • Request timeout
      • Channel closed
You can check the valid/invalid status of a webhook using the GET /2/webhooks endpoint or via the toolbox in the Developer Console.

​
Getting started

Prerequisites
  • An approved developer account
  • A Project and App in the Developer Console
  • A publicly accessible HTTPS endpoint
  • One of the following webhook signing secrets for CRC validation and signature verification:
    • Recommended: your app’s OAuth 2.0 client secret (the Client Secret shown for the app in the Developer Console)
    • Your app’s OAuth 1.0 consumer secret (API Secret Key) — supported for backward compatibility with existing OAuth 1.0 integrations

Quickstart

Set up your webhook end-to-end

Filtered Stream Webhooks

Receive filtered Posts via webhook

Account Activity API

Receive account events via webhook

Sample apps

Working code examples