Webhooks

Create a subscription

Open Settings → Developer, select a live credential with webhooks:manage, enter a public HTTPS endpoint, and choose event types. ClassFlow shows the signing secret once.

Event payload

{
  "id": "95977a17-d6bf-4e9b-9a84-94ce9ef5e52d",
  "type": "form.submitted",
  "api_version": "2026-08-08",
  "created_at": "2026-08-02T21:15:00Z",
  "studio_id": "8d39560b-50fd-46d1-a543-b11a3525479c",
  "data": {
    "object": {
      "id": "8350c2ed-aee7-4f52-8745-45765f899518",
      "object": "form_submission"
    }
  }
}

Payloads contain stable identifiers and event metadata. Fetch the current object through the scoped Partner API when you need the latest fields.

Verify every signature

import crypto from "node:crypto";

const signed = Buffer.concat([
  Buffer.from(req.headers["x-classflow-timestamp"] + "."),
  rawBody,
]);

const expected = "v1=" + crypto
  .createHmac("sha256", process.env.CLASSFLOW_WEBHOOK_SECRET)
  .update(signed)
  .digest("hex");

const supplied = Buffer.from(req.headers["x-classflow-signature"] ?? "");
const calculated = Buffer.from(expected);

if (supplied.length !== calculated.length ||
    !crypto.timingSafeEqual(calculated, supplied)) {
  throw new Error("Invalid ClassFlow signature");
}

Delivery behavior

• Persist the event to your queue, then return a 2xx response within 10 seconds.
• Deduplicate with X-ClassFlow-Delivery. Related events can arrive out of order.
• The first attempt is immediate. Failed deliveries retry after 1 minute, 5 minutes, 15 minutes, 1 hour, 3 hours, 6 hours, and 12 hours: eight attempts total.
• After the final failed attempt, the delivery moves to dead-letter state.

Event catalog

Replay and secret rotation

Studio operators can inspect every HTTP attempt, replay a delivery, disable a subscription, and rotate its signing secret from Settings → Developer. Rotating the owning API credential transfers active subscriptions to the replacement credential.