Twitter (X) Webhooks — A Real-Time API Guide
'Twitter webhooks' as a term overloads two very different APIs. If you're building a bot that reacts to mentions and DMs on one specific X account you own, you want the Account Activity API. If you're building a monitoring product that reacts to any matching tweet content anywhere, you want a rule-based webhook. This guide walks both.
Pricing references URL-cited to each provider's published documentation.
Two products, one word — which webhook do you actually want?
X Account Activity API (AAA): subscribe to events on a specific X account you own. Delivered events: mentions of the account, DMs sent to it, follows / unfollows, blocks, tweet deletes. You cannot use AAA to monitor tweets from other accounts — it's per-account for accounts you have OAuth on. Gated to Premium developer tier per X's current pricing.
twitterapi.io tweet_filter webhook: register a rule (matching any tweet content, from anyone). twitterapi.io POSTs matching tweets to your callback URL. Not tied to any one account; matches happen globally based on your rule. Standard use for brand monitoring, keyword alerts, real-time content aggregators.
Which you want: 'I own @mybrand and want events on it' → AAA. 'I want to know when anyone mentions my brand / a keyword / a topic' → tweet_filter.
Path 1 — twitterapi.io tweet_filter webhook
Register a rule programmatically. Provide a callback URL via the dashboard. Matching tweets get POSTed to your callback as they arrive.
Pricing per twitterapi.io/pricing: $0.00015 per matched tweet delivered.
import os, requests
HEADERS = {"X-API-Key": os.environ["TWITTERAPI_IO_KEY"]}
BASE = "https://api.twitterapi.io"
def register_rule(tag: str, value: str):
r = requests.post(
f"{BASE}/oapi/tweet_filter/add_rule",
headers=HEADERS,
data={
"tag": tag,
"value": value,
"interval_seconds": 5,
},
timeout=15,
)
r.raise_for_status()
return r.json()
# Register
rule = register_rule("brand-mentions", '"YourBrand" -is:retweet lang:en')
print(f"rule id: {rule.get('rule_id')}")Path 2 — X Account Activity API (AAA)
Register a webhook via the AAA API. Subscribe an OAuth'd account to that webhook. Events on that account get POSTed to your endpoint.
Pricing per docs.x.com/x-api/getting-started/pricing: Premium tier and up. Setup requires X Developer Console app + OAuth for each subscribed account.
# pip install tweepy requests-oauthlib
# AAA setup is more involved: register webhook, verify challenge, subscribe accounts.
#
# Simplified illustration:
import requests
from requests_oauthlib import OAuth1
AUTH = OAuth1(
"CONSUMER_KEY", "CONSUMER_SECRET",
"USER_TOKEN", "USER_TOKEN_SECRET",
)
# 1. Register your webhook URL
r = requests.post(
"https://api.x.com/2/webhooks",
auth=AUTH,
data={"url": "https://your-app.com/aaa-callback"},
)
print(r.json()) # includes webhook id
# 2. Subscribe an OAuth'd account
r = requests.post(
"https://api.x.com/2/subscriptions",
auth=AUTH,
)
# Now events on THAT specific account POST to your callbackSide-by-side — 2 webhook paths
Two practical observations: (a) product-level monitoring (brand / keyword / topic) is almost always the tweet_filter use case; (b) AAA covers a niche — bots on accounts you own — that tweet_filter can't (DMs, follows, blocks aren't visible to public content filtering).
Common webhook patterns
Brand-mention alerting: tweet_filter with "YourBrand" rule → webhook → Slack/PagerDuty. Latency seconds; cost single-digit dollars/month at typical volumes.
Keyword firehose: tweet_filter with broad rule → webhook → your queue → downstream processing. See /blog/twitter-firehose-api-developer-guide for the volume-tier discussion.
Custom X bot on your own account: AAA + reply / follow-back / DM automation. Only path 2 (AAA) exposes these events.
Reply-to-mention bot: AAA for the mention notification + X official POST endpoint to send the reply. Requires OAuth + Premium tier.
Content-triggered notification service: tweet_filter with product-related keywords → webhook → notification queue → user-specific push notifications.
Picking the path
'I want to know when anyone tweets X': twitterapi.io tweet_filter. Match on content; standard monitoring pattern.
'I want to build a bot on @myaccount that reacts to mentions/DMs': X Account Activity API. Path 2 is required for OAuth-based per-account events.
Both: some products use both — AAA for the bot's own account events, tweet_filter for the broader listening surface.
Most product / monitoring workflows land at tweet_filter because setup is simpler + coverage is broader (any content vs one account).
# Practical example: content-triggered notification service on twitterapi.io webhook.
import os, requests
HEADERS = {"X-API-Key": os.environ["TWITTERAPI_IO_KEY"]}
BASE = "https://api.twitterapi.io"
def register_content_watcher(topic: str, callback_url: str):
r = requests.post(
f"{BASE}/oapi/tweet_filter/add_rule",
headers=HEADERS,
data={
"tag": f"watcher-{topic}",
"value": f'"{topic}" -is:retweet lang:en min_faves:10',
"interval_seconds": 5,
},
timeout=15,
)
r.raise_for_status()
return r.json()
# Webhook handler (FastAPI illustration)
from fastapi import FastAPI, Request
app = FastAPI()
@app.post("/twitter-callback")
async def receive(request: Request):
body = await request.json()
tweet = body["tweet"]
tag = body["tag"]
# Route by tag to per-topic subscribers
subscribers = get_subscribers_for(tag)
for sub in subscribers:
send_push_notification(sub, tweet)
return {"ok": True}
# One-time rule registration
# register_content_watcher("AI safety", "https://your-app.com/twitter-callback")
# Cost per twitterapi.io/pricing:
# ~2000 matched tweets/day × $0.00015 = $0.30/day = ~$9/month for one active topic
# For AAA equivalent: Premium tier subscription base + per-event fee at Premium ratesQuestions readers ask
Can I use webhooks to monitor tweets from any account?
Yes with twitterapi.io tweet_filter — the rule matches on content, not on a specific account. To monitor a specific user's tweets: from:username in your rule value. X's AAA only surfaces events on accounts you have OAuth on.
What events can I get through the Account Activity API?
Mentions of the account, DMs sent to it, follows/unfollows, blocks/unblocks, tweet deletes on the account. All tied to a specific account you have OAuth on. Public read-only events on other accounts are NOT covered — for that you need content filtering (tweet_filter path).
Are webhooks reliable / guaranteed delivery?
Both providers retry on transient failures; check their published retry policies. For guaranteed processing, run your webhook behind a queue (SQS / Kafka / Redis) — receive-and-ack fast + async workers do real processing. This prevents transient endpoint issues from losing messages.
Does the webhook include the full tweet object?
Yes — twitterapi.io delivers the full tweet JSON (text, author metadata, public_metrics, entities). Same shape as advanced_search response. AAA delivers event-specific payloads (mention text, DM contents, follow record, etc.) shaped by event type.
Can I filter webhook events at delivery time?
twitterapi.io applies your rule filter server-side (only matching tweets are POSTed to you). You still filter further client-side if needed (e.g., keyword blacklist). AAA delivers all events for subscribed accounts — you filter your side.
How do I verify the webhook actually came from the provider?
twitterapi.io includes an HMAC signature header (specifics in their webhook documentation) so you can verify authenticity + reject spoofed callbacks. AAA uses a CRC challenge on setup + optional signature on each callback.
Continue
- Twitter (X) API — cluster hub
- Using webhooks for real-time Twitter (X) data
- Twitter (X) streaming API — real-time guide
- Twitter (X) firehose API — developer guide
- twitterapi.io pricing
Stop reading. Start building.
Starter credits cover real testing on real data. Google sign-in, no card, no application queue.
Get an API key