Webhooks

Set up

On a Form's Integrations tab. Up to five per Form. The secret is masked on screen but stays available through the Copy secret button — while the Studio has no login, treat anyone who can reach the Studio as someone who can reach the secrets.

What arrives

{
  "event": "submission.created",
  "submission": {
    "id": "7e583034-1a0a-47d5-ab72-74d4541f8486",
    "formId": "form_survey_demo",
    "receivedAt": 1788182240254,
    "origin": "https://app.acme.com",
    "userAgent": "Mozilla/5.0 …",
    "source": "api",
    "sender": null,
    "sourceRef": null,
    "payload": { "satisfaction": 5, "plan": "pro" }
  }
}

payload is what ingest stored: what arrived, with the Form's defaults and locked values written in. source, sender and sourceRef are the Submission's provenance — which door it came through, who sent it, and a link back to the original.

submission.status_changed

Sent when a person moves a Submission to another status word. change sits beside submission:

{
  "event": "submission.status_changed",
  "change": {
    "entryId": "0d3c…",
    "from": "new",
    "to": "planned",
    "note": "AMP-7501",
    "by": "ana@acme.com",
    "at": 1788182240254
  },
  "submission": { "id": "7e58…", "formId": "…", "source": "slack", "…": "…" }
}

entryId is the change's entry on the Submission's Timeline. Every change is one delivery. A note edited without moving the word goes on the Timeline but sends nothing.

Verify the signature

HMAC-SHA256 over `${timestamp}.${body}`, using the raw body — before any parsing. The timestamp is part of the signed string so a captured request cannot be replayed with a fresh time.

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

export function verify(req, secret) {
  const ts = req.headers["x-noonmark-timestamp"];
  const sent = req.headers["x-noonmark-signature"];

  // Reject anything older than five minutes.
  if (Math.abs(Date.now() - Number(ts)) > 300_000) return false;

  const mac = createHmac("sha256", secret)
    .update(`${ts}.${req.rawBody}`)
    .digest("hex");

  const expected = Buffer.from(`sha256=${mac}`);
  const actual = Buffer.from(sent);
  return expected.length === actual.length
    && timingSafeEqual(expected, actual);
}

Delivery

Each delivery is recorded once, after its last attempt, with its status, code, attempt count, duration and error. The log is visible on the Form's Integrations tab and on the Workspace's Integrations page. There is one row per webhook per Submission for created and accepted, and one per status change for status_changed.