Webhooks

Receive signed HTTP POST requests when a monitor detects a new tweet. Available on Starter plan and above.

Setup

1. Upgrade to Starter or higher
2. Dashboard → Monitors → expand Webhook section on a monitor
3. Enter your HTTPS endpoint URL and save
4. Copy the signing secret shown once — store it securely
5. Click Test webhook to verify connectivity

Delivery

When a new hit is recorded, XFlux POSTs JSON to your URL with these headers:

Content-Type: application/json
X-XFlux-Event: monitor.hit
X-XFlux-Timestamp: 1710000000
X-XFlux-Signature: sha256=<hex>
User-Agent: XFlux-Webhook/1.0

Hit payload

{
  "event": "monitor.hit",
  "monitor": {
    "id": "clx...",
    "targetUsername": "elonmusk",
    "keywords": null
  },
  "tweet": {
    "id": "1234567890",
    "text": "Hello world",
    "authorUsername": "elonmusk",
    "createdAt": "2026-06-14T12:00:00.000Z"
  },
  "detectedAt": "2026-06-14T12:00:05.000Z"
}

Test payload

{
  "event": "monitor.test",
  "monitor": {
    "id": "clx...",
    "targetUsername": "elonmusk",
    "keywords": null
  },
  "test": true
}

Verify signatures

Compute HMAC-SHA256 over {timestamp}.{raw_body} using your webhook secret. Reject requests older than 5 minutes.

import crypto from "crypto";

function verify(secret, timestamp, rawBody, signatureHeader) {
  const expected = "sha256=" + crypto
    .createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signatureHeader)
  );
}

// Express example
app.post("/webhooks/xflux", express.raw({ type: "application/json" }), (req, res) => {
  const timestamp = req.headers["x-xflux-timestamp"];
  const signature = req.headers["x-xflux-signature"];
  const rawBody = req.body.toString("utf8");

  if (!verify(WEBHOOK_SECRET, timestamp, rawBody, signature)) {
    return res.status(401).send("Invalid signature");
  }

  const event = JSON.parse(rawBody);
  // handle monitor.hit ...
  res.status(200).send("ok");
});

Retries & logs

Each delivery attempt is logged in Dashboard (status code, latency, error message). Failed deliveries are not automatically retried in the current version — use Test webhook after fixing your endpoint.