> ## Documentation Index
> Fetch the complete documentation index at: https://x-preview-mintlify-b8e3e38a.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# V2 Webhooks API
> The V2 Webhooks API enables developers to receive real-time event notifications from X accounts. Reference for the X API v2 standard tier covering webhooks.
export const Button = ({href, children}) => {
return ;
};
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
Receive events instantly as they occur
Data sent directly to your server — no polling
CRC validation and signature verification
Retry and recovery support
***
## Products that support webhooks
These are the products that currently support delivering events via webhook:
| Product | Description |
| :- | :- |
| [X Activity API (XAA)](/x-api/activity/introduction) | Receive real-time events for activity happening on X |
| [Account Activity API (AAA)](/x-api/account-activity/introduction) | Receive real-time events tied to specific user accounts |
| [Filtered Stream Webhooks](/x-api/webhooks/stream/introduction) | Receive filtered stream Posts via webhook delivery |
***
## How webhooks work
```mermaid actions={false} theme={null}
flowchart LR
A["X Event
Occurs"] --> B["X Server"] --> C["Your
Webhook URL"]
```
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
| Requirement | Description |
| :- | :- |
| **HTTPS** | Webhook URL must use HTTPS |
| **Publicly accessible** | URL must be reachable from the internet |
| **No port specification** | The URL cannot include a port (e.g., `https://mydomain.com:5000/webhook` will not work) |
| **Fast response** | Respond within 10 seconds |
| **200 OK** | Return 200 status to acknowledge receipt |
| **CRC support** | Must respond to Challenge-Response Check GET requests ([learn more](/x-api/webhooks/quickstart#2-the-crc-check)) |
***
## Endpoints
| Method | Endpoint | Description |
| :- | :- | :- |
| POST | [`/2/webhooks`](/x-api/webhooks/create-webhook) | Register a new webhook |
| GET | [`/2/webhooks`](/x-api/webhooks/get-webhook) | List registered webhooks |
| DELETE | [`/2/webhooks/:webhook_id`](/x-api/webhooks/delete-webhook) | Delete a webhook |
| POST | [`/2/webhooks/replay`](/x-api/webhooks/create-replay-job-for-webhook) | Create a replay job for webhook |
| PUT | [`/2/webhooks/:webhook_id`](/x-api/webhooks/validate-webhook) | Trigger 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.
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](https://developer.x.com/en/portal/petition/essential/basic-info)
* A [Project and App](/resources/fundamentals/developer-apps) in the Developer Console
* A publicly accessible HTTPS endpoint
* Your app's **consumer secret** (API secret key) for CRC validation
Set up your webhook end-to-end
Receive filtered Posts via webhook
Receive account events via webhook
Working code examples