Webhooks

x-firstflow-webhook-signature: v1,<hex hmac of `${timestamp}.${body}`>

import { createHmac, timingSafeEqual } from "crypto";

const TOLERANCE_SECONDS = 5 * 60;

// `rawBody` is the exact request body string. `WEBHOOK_SECRET` is the secret
// you configured on the Webhook node / logic action.
function verify(rawBody: string, headers: Record<string, string>): boolean {
  const timestamp = headers["x-firstflow-webhook-timestamp"];
  const header = headers["x-firstflow-webhook-signature"]; // "v1,<hex>"
  if (!timestamp || !header) return false;

  // Reject replays: drop deliveries whose timestamp drifts too far from now.
  const skew = Math.abs(Math.floor(Date.now() / 1000) - Number(timestamp));
  if (!Number.isFinite(skew) || skew > TOLERANCE_SECONDS) return false;

  const expected = createHmac("sha256", process.env.WEBHOOK_SECRET!)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex");

  const [version, candidate] = header.split(",");
  if (version !== "v1" || !candidate) return false;

  const a = Buffer.from(candidate);
  const b = Buffer.from(expected);
  return a.length === b.length && timingSafeEqual(a, b);
}

{
  "type": "experience.logic_action.webhook",
  "version": 1,
  "data": {
    "entityId": "exp_…",
    "occurredAt": "2026-06-08T12:00:00.000Z",
    "agentId": "agt_…",
    "experienceId": "exp_…",
    "source": "node_trigger",
    "actionIndex": 0
  }
}

const res = await fetch(
  `https://api.firstflow.app/v1/agents/${agentId}/experiences/${experienceId}/logic-webhook`,
  {
    method: "POST",
    headers: {
      authorization: `Bearer ${token}`,
      "content-type": "application/json",
    },
    body: JSON.stringify({
      idempotencyKey: "order-4187-provisioned", // your stable key, ≤ 200 chars
      source: "node_trigger",                   // or "experience_trigger"
      nodeId: "node_…",                         // required for node_trigger
      nodeTriggerGroupId: "grp_…",              // required for node_trigger
      actionIndex: 0,                           // which action in the group
    }),
  },
);

// 202 Accepted on first call → row enqueued for delivery
// 204 No Content on a duplicate idempotencyKey → nothing enqueued