X Activity API webhooks: events, scopes, and costs

Why webhooks got interesting in 2026

Under the old subscription tiers, polling was free at the margin. You paid $200 a month and made as many calls as your rate limit allowed. Under pay-per-use, every poll costs money whether or not it returns anything.

Do the arithmetic on a one-minute mention poller. That is 43,200 requests a month. Most of them return nothing, and the ones that do return posts bill at $0.005 each. A webhook charges you only when something actually happened, capped at $0.010 for the most expensive event type. For anything below a few hundred events a day, push beats pull by an order of magnitude.

The 2026 additions matter because they close the gaps that forced people back to polling. post.create means you no longer need to poll your own timeline to know a post went out. post.delete, which is free, means you no longer need to re-read your posts to discover one vanished. mute and block turn a previously invisible negative signal into a feed.

# 1. Register the webhook URL for your dev environment
curl -X POST "https://api.x.com/2/webhooks" \
  -H "Authorization: Bearer $X_APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://your-app.example.com/x/events" }'

# 2. Subscribe the authorizing user's account to it.
#    mute and block require OAuth 2.0 with mute.read / block.read.
curl -X POST "https://api.x.com/2/webhooks/$WEBHOOK_ID/subscriptions" \
  -H "Authorization: Bearer $X_USER_ACCESS_TOKEN"

Two things to get right up front. First, mute and block need OAuth 2.0 with mute.read and block.read. If your app is still on OAuth 1.0a for the older Activity API events, you need a second authorization path. Second, your handler must return 2xx quickly. X retries failed deliveries, and a retried delivery of a billable event is a delivery you can be charged for.

// Your handler. Every delivery you accept is a billable event,
// except post.delete and dm.sent, which are free.
export async function POST(req: Request) {
  const body = await req.json();

  if (body.post_delete_events) {
    // Free event. Log it, alert on it, reconcile your own records.
    await markPostMissing(body.post_delete_events[0].id);
  }

  if (body.post_create_events) {
    // Billable. Only subscribe if you will act on it.
    await archivePost(body.post_create_events[0]);
  }

  return new Response(null, { status: 200 });
}

The other direction: connectors

An X webhook tells you what happened on X. Most of the automations people build are the mirror image: something happened in your systems, and it should become a post. That is what OpenTweet connectors do, and they need no X developer account, no webhook registration, and no per-event billing.

• GitHub connector: a release, a merged PR, or a commit becomes a drafted post.
• Stripe connector: revenue milestones and metric moves become build-in-public posts.
• RSS connector: a new item in any feed becomes a scheduled post, with no $0.20 link surcharge.
• A generic API connector for anything you can POST to, if you would rather push events yourself.

And if you would rather do the plumbing yourself, one REST call from your own webhook handler is enough:

# Outbound, the other direction: a connector turns an event in
# your own systems into a scheduled post, with no X developer account.
curl -X POST https://opentweet.io/api/v1/posts \
  -H "Authorization: Bearer ot_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "New release is live. Changelog in the replies.",
    "scheduled_date": "2026-09-02T15:00:00Z"
  }'