Get a signed POST when a node is about to go away.

Quickstart

From zero to verified delivery in two commands.

iframe instances webhook set inst-... \
  --url https://hooks.example.com/iframe \
  --events advisory,warning,offline

# → Webhook configured.
# →   Secret id  : whsec_ab12cd34 (v1)
# →   Secret     : 7f3a1b9c7d5e2f4a6b8c0d3e1f5a7b9c   ← shown once

iframe instances webhook test inst-... --event warning
# → Delivered   : yes
# → HTTP status : 200

Wire format

Four fields. Nothing else.

{
  "event":     "advisory" | "warning" | "offline",
  "ip":        "203.0.113.42",
  "timestamp": "2026-05-21T01:13:33.530Z",
  "message":   "Node disruption imminent"
}

Reference receiver

Drop-in Node receiver. Zero dependencies.

Save as iframe-receiver.js, set IFRAME_SECRETS_FILE to a JSONL of {resource_id, secret_id, secret, public_ip} rows, run. The handler verifies the signature against every loaded secret in constant time, identifies which node the event is for by which secret matched, dedupes by X-IFrame-Event-Id, and rejects replays older than 5 minutes.

"use strict";
const fs = require("node:fs");
const http = require("node:http");
const crypto = require("node:crypto");

const PORT = Number(process.env.IFRAME_PORT || 8443);
const URL_PATH = process.env.IFRAME_PATH || "/iframe-events";
const SECRETS_FILE = process.env.IFRAME_SECRETS_FILE;
const MAX_SKEW_SEC = 300;

const SECRETS = fs
  .readFileSync(SECRETS_FILE, "utf8")
  .split(/\r?\n/)
  .filter(Boolean)
  .map((l) => JSON.parse(l))
  .filter((r) => r.secret && r.resource_id);

const seen = new Map();
function alreadySeen(id) {
  const ttl = 30 * 60_000;
  const ts = seen.get(id);
  if (ts && Date.now() - ts < ttl) return true;
  seen.set(id, Date.now());
  return false;
}

const SIG_RE = /^t=(\d+),v1=([0-9a-f]{64})$/;
function verify(sig, raw) {
  const m = SIG_RE.exec(sig || "");
  if (!m) return null;
  const ts = Number(m[1]);
  if (Math.abs(Math.floor(Date.now() / 1000) - ts) > MAX_SKEW_SEC) return null;
  const provided = Buffer.from(m[2], "hex");
  const signed = `${ts}.${raw.toString("utf8")}`;
  for (const s of SECRETS) {
    const mac = crypto.createHmac("sha256", s.secret).update(signed).digest();
    if (mac.length === provided.length &&
        crypto.timingSafeEqual(mac, provided)) {
      return { resource_id: s.resource_id, public_ip: s.public_ip };
    }
  }
  return null;
}

function readBody(req) {
  return new Promise((res, rej) => {
    let n = 0; const chunks = [];
    req.on("data", (c) => { n += c.length; if (n > 32768) { req.destroy(); rej(new Error("too large")); } else chunks.push(c); });
    req.on("end", () => res(Buffer.concat(chunks)));
    req.on("error", rej);
  });
}

http.createServer(async (req, res) => {
  if (req.method !== "POST" || req.url !== URL_PATH) {
    return res.writeHead(404).end();
  }
  let raw;
  try { raw = await readBody(req); }
  catch { return res.writeHead(400).end(); }

  const eventId = String(req.headers["x-iframe-event-id"] || "");
  if (!eventId) return res.writeHead(400).end();

  const v = verify(req.headers["x-iframe-signature"], raw);
  if (!v) return res.writeHead(401).end();
  if (alreadySeen(eventId)) return res.writeHead(200).end('{"ok":true,"deduped":true}');

  const payload = JSON.parse(raw.toString("utf8"));

  // === your business logic here ===
  // payload.event ∈ {advisory, warning, offline}
  // payload.ip, payload.timestamp, payload.message
  // v.resource_id identifies which node this is for
  console.log(`[iframe] ${eventId} ${payload.event} node=${v.resource_id} ip=${payload.ip}`);

  res.writeHead(200, { "content-type": "application/json" });
  res.end('{"ok":true}');
}).listen(PORT, () => console.log(`listening :${PORT}${URL_PATH}`));

Keep the response under 3 seconds — anything slower counts as failure and triggers a retry. The HMAC trial loop is microseconds even with hundreds of secrets, so push the queue write and process the event asynchronously.

CLI reference

iframe instances webhook *

Activation is CLI-only and per-instance. The API key needs the instances:webhook scope.

iframe instances webhook set <id> \
  --url <https-url> \
  --events advisory,warning,offline

  --url     required; must be https://, public DNS, no credentials in the URL
  --events  required; comma-separated subset of advisory,warning,offline

iframe instances webhook get inst-...
# Webhook       : enabled
# URL           : https://hooks.example.com/iframe
# Events        : advisory, warning, offline
# Secret id     : whsec_ab12cd34 (v2)
# Last success  : 2026-05-21T01:13:33.139Z

iframe instances webhook rotate inst-...

iframe instances webhook test <id> [--event advisory|warning|offline]

  --event   defaults to advisory
# Test event  : warning
# Event id    : evt_pf7m9ny86zre84whc7n7w29fjmf8c
# Delivered   : yes
# Attempts    : 1
# HTTP status : 200

iframe instances webhook deliveries inst-... [--limit N]

# 2026-05-21T01:13:33.530Z  warning   attempt 1  ok  HTTP 200  3ms
# 2026-05-21T01:13:32.019Z  advisory  attempt 1  ok  HTTP 200  6ms
# 2026-05-21T01:13:29.442Z  warning   attempt 1  ok  HTTP 200  29ms  [synthetic]

iframe instances webhook remove inst-...

Observability

What's recorded, what's queryable.

iframe instances webhook deliveries inst-... --limit 100