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:
ProductDescription
X Activity API (XAA)Receive real-time events for activity happening on X (open beta)
Account Activity API (AAA)Receive real-time events tied to specific user accounts
Filtered Stream WebhooksReceive filtered stream Posts via webhook delivery

​
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

RequirementDescription
HTTPSWebhook URL must use HTTPS
Publicly accessibleURL must be reachable from the internet
No port specificationThe URL cannot include a port (e.g., https://mydomain.com:5000/webhook will not work)
Fast responseRespond within 10 seconds
200 OKReturn 200 status to acknowledge receipt
CRC supportMust respond to Challenge-Response Check GET requests (learn more)

​
Endpoints

MethodEndpointDescription
POST/2/webhooksRegister a new webhook
GET/2/webhooksList registered webhooks
DELETE/2/webhooks/:webhook_idDelete a webhook
POST/2/webhooks/replayCreate a replay job for webhook
PUT/2/webhooks/:webhook_idTrigger CRC check and re-enable a webhook
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 an x-twitter-webhooks-signature header. You can verify this signature to confirm X is the source of incoming events.

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
  • Your app’s consumer secret (API secret key) for CRC validation

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