Twitter webhook Node.js handler (XFlux signed POSTs)

Node.js setup

1. 1

   Create monitor + webhook URL pointing at your server

   Expose HTTPS (ngrok for local tests). Save the signing secret from the Dashboard.

2. 2

   Implement verification middleware

   Reject missing headers, skew > 5 minutes, or bad signatures with 401.

3. 3

   Handle monitor.hit and monitor.test

   Test events validate connectivity; hit events are live matches on Starter+.

Express verification example

Production code should load the secret from env and log failures without echoing secrets.

import express from "express";
import crypto from "crypto";

const app = express();
const secret = process.env.XFLUX_WEBHOOK_SECRET!;

app.post(
  "/webhooks/xflux",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const ts = req.header("X-XFlux-Timestamp") || "";
    const sig = req.header("X-XFlux-Signature") || "";
    const raw = req.body.toString("utf8");
    const expected =
      "sha256=" +
      crypto.createHmac("sha256", secret).update(`${ts}.${raw}`).digest("hex");
    const a = Buffer.from(sig);
    const b = Buffer.from(expected);
    if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
      return res.status(401).end();
    }
    const event = JSON.parse(raw);
    if (event.event === "monitor.hit") {
      console.log(event.tweet.authorUsername, event.tweet.text);
    }
    res.status(200).send("ok");
  }
);

FAQ

Python example?

Same header scheme — see /docs/webhooks and /docs/guides/python. This page focuses on Node.js.

Discord without a server?

Paste a Discord Incoming Webhook URL into XFlux — no Node process required. See /twitter-discord-alerts.

Official Twitter CRC challenge?

XFlux uses HMAC on our payloads, not the official AAA CRC challenge. Do not mix verifiers.

Related guides

• Full webhook docs
• Node.js API guide
• n8n path
• Monitor + webhook guide