Test X (Twitter) webhooks locally

Receive X account events on your laptop while you build, with an HTTPS URL X can reach.

Before you beginCopy Anchor Link

• Node.js 18 or later
• A Horizon account and the CLI (see Getting started)
• A reserved subdomain for -s. Reserve one on the Subdomains page.
• A Next.js app that uses the App Router and runs on port 3000
• An X developer app with its OAuth 2.0 client secret, and an App Only Bearer Token
• A way to send curl requests

import { createHmac, timingSafeEqual } from "node:crypto";

function sign(clientSecret: string, message: string) {
  return `sha256=${createHmac("sha256", clientSecret).update(message).digest("base64")}`;
}

export async function GET(request: Request) {
  const clientSecret = process.env.X_CLIENT_SECRET;
  const crcToken = new URL(request.url).searchParams.get("crc_token");

  if (!clientSecret || !crcToken) {
    return new Response("Missing crc_token or X_CLIENT_SECRET", { status: 400 });
  }

  return Response.json({ response_token: sign(clientSecret, crcToken) });
}

export async function POST(request: Request) {
  const clientSecret = process.env.X_CLIENT_SECRET;
  if (!clientSecret) {
    return new Response("Missing X_CLIENT_SECRET", { status: 500 });
  }

  const body = await request.text();
  const received = request.headers.get("x-twitter-webhooks-signature-oauth2") ?? "";
  const expected = sign(clientSecret, body);

  const receivedBuffer = Buffer.from(received);
  const expectedBuffer = Buffer.from(expected);
  const isValid =
    receivedBuffer.length === expectedBuffer.length &&
    timingSafeEqual(receivedBuffer, expectedBuffer);

  if (!isValid) {
    return new Response("Invalid signature", { status: 401 });
  }

  const payload = JSON.parse(body);
  const eventTypes = Object.keys(payload).filter((key) => key.endsWith("_events"));
  console.log(`Received X events for user ${payload.for_user_id}: ${eventTypes.join(", ")}`);

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

X_CLIENT_SECRET=replace-with-your-oauth2-client-secret

npm run dev

hrzn tunnel http://localhost:3000 -s my-app

HORIZON: Tunnel connected
  URL          https://my-app.hrzn.run (reserved)
  Forwarding   http://localhost:3000
  Request log  https://hrzn.run/dashboard/tunnels/my-app

curl --request POST \
  --url 'https://api.x.com/2/webhooks' \
  --header "Authorization: Bearer $BEARER_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"url": "https://my-app.hrzn.run/api/webhooks/x"}'

Check it worksCopy Anchor Link

The registration call makes X send a CRC request. In the terminal that runs hrzn, you see a GET line with status 200:

  GET     200  /api/webhooks/x

To send a real event, post from the subscribed account. X sends a tweet_create_events payload. The Horizon terminal prints:

  POST    200  /api/webhooks/x

Your app terminal prints a line like:

Received X events for user 1234567890: tweet_create_events

To ask X to run the CRC again, send PUT /2/webhooks/:webhook_id. To list your webhooks, send GET /2/webhooks.

TroubleshootingCopy Anchor Link

Registration fails because the CRC check failsCopy Anchor Link

X marks the webhook invalid, and no events arrive.

• Check that X_CLIENT_SECRET is the OAuth 2.0 client secret of the app that registers the webhook. Restart npm run dev after you edit .env.local.
• Check that the JSON body is {"response_token": "sha256=..."} and that the token is base64, not hex.
• Check that the URL ends with /api/webhooks/x and that the Horizon tunnel is running.

The signature doesn't matchCopy Anchor Link

The Horizon line shows [401] for a POST request.

• Check the header name. This page verifies X-Twitter-Webhooks-Signature-OAuth2 with the OAuth 2.0 client secret. The legacy X-Twitter-Webhooks-Signature header uses the OAuth 1.0 consumer secret.
• Compute the HMAC over the raw body. Don't run JSON.parse and JSON.stringify first, because that can change the bytes.

Events stopped arrivingCopy Anchor Link

X re-runs the CRC every hour. If it fails, X marks the webhook invalid and stops delivery. Fix the handler, then send PUT /2/webhooks/:webhook_id to re-validate. If you restarted the tunnel without -s, the URL changed and the old one is dead. Restart with -s my-app, see Pricing.

Nothing reaches your appCopy Anchor Link

• Check that the Horizon terminal is still running. If its last line is Connection lost. Reconnecting…, wait for Reconnected.
• Check that you subscribed the account. A registered webhook with no subscription gets no account events.

Next stepsCopy Anchor Link

• Read X's webhooks quickstart.
• Read X's Account Activity API docs for every event type.
• X's xurl tool has a xurl webhook start command that runs a temporary webhook and handles the CRC check for you.