fal.ai Webhooks: Payload Format, Retries and Signature Verification

curl --request POST \
  --url 'https://queue.fal.run/fal-ai/flux/dev?fal_webhook=https://url.to.your.app/api/fal/webhook' \
  --header "Authorization: Key $FAL_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"prompt": "Photo of a cute dog"}'

# Response: the request is queued, the result arrives later on your webhook
# {"request_id": "024ca5b1-...", "gateway_request_id": "024ca5b1-..."}

{
  "request_id": "123e4567-e89b-12d3-a456-426614174000",
  "gateway_request_id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "OK",
  "payload": {
    "images": [
      {
        "url": "https://url.to/image.png",
        "content_type": "image/png",
        "file_name": "image.png",
        "file_size": 1824075,
        "width": 1024,
        "height": 1024
      }
    ],
    "seed": 196619188014358660
  }
}

{
  "request_id": "5b1d7e2a-9c4f-4a8e-b0d3-2f6e8a1c9d47",
  "gateway_request_id": "5b1d7e2a-9c4f-4a8e-b0d3-2f6e8a1c9d47",
  "status": "OK",
  "payload": {
    "video": {
      "url": "https://url.to/output.mp4",
      "content_type": "video/mp4",
      "file_name": "output.mp4",
      "file_size": 4718592
    }
  }
}

{
  "request_id": "123e4567-e89b-12d3-a456-426614174000",
  "gateway_request_id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "ERROR",
  "error": "Invalid status code: 422",
  "payload": {
    "detail": [
      {
        "loc": ["body", "prompt"],
        "msg": "field required",
        "type": "value_error.missing"
      }
    ]
  }
}

import crypto from "node:crypto";

const JWKS_URL = "https://rest.fal.ai/.well-known/jwks.json";
const JWKS_TTL_MS = 24 * 60 * 60 * 1000; // fal.ai allows caching for up to 24 h
let jwksCache = { keys: [], fetchedAt: 0 };

async function getPublicKeys() {
  if (Date.now() - jwksCache.fetchedAt > JWKS_TTL_MS) {
    const res = await fetch(JWKS_URL);
    const { keys } = await res.json();
    jwksCache = {
      keys: keys.map((jwk) => crypto.createPublicKey({ key: jwk, format: "jwk" })),
      fetchedAt: Date.now(),
    };
  }
  return jwksCache.keys;
}

// rawBody must be the exact bytes fal.ai sent (a Buffer), not re-serialized JSON
export async function verifyFalWebhook(headers, rawBody) {
  const requestId = headers["x-fal-webhook-request-id"];
  const userId = headers["x-fal-webhook-user-id"];
  const timestamp = headers["x-fal-webhook-timestamp"];
  const signatureHex = headers["x-fal-webhook-signature"];
  if (!requestId || !userId || !timestamp || !signatureHex) return false;

  // 1. Reject deliveries more than 5 minutes off
  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - parseInt(timestamp, 10)) > 300) return false;

  // 2. Rebuild the signed message
  const bodyHash = crypto.createHash("sha256").update(rawBody).digest("hex");
  const message = Buffer.from([requestId, userId, timestamp, bodyHash].join("\n"), "utf8");
  const signature = Buffer.from(signatureHex, "hex");

  // 3. Any current fal.ai key may have signed it
  const keys = await getPublicKeys();
  return keys.some((key) => crypto.verify(null, message, key, signature));
}

import express from "express";
import { verifyFalWebhook } from "./verify-fal.js";

const app = express();

app.post("/api/fal/webhook", express.raw({ type: "application/json" }), async (req, res) => {
  if (!(await verifyFalWebhook(req.headers, req.body))) {
    return res.status(401).end();
  }

  const event = JSON.parse(req.body.toString("utf8"));
  res.status(200).end(); // acknowledge fast; fal.ai's first attempt times out at 15 s

  if (await alreadyProcessed(event.request_id)) return; // retries reuse request_id

  if (event.status === "OK" && event.payload) {
    const urls = [
      ...(event.payload.images ?? []).map((img) => img.url),
      event.payload.video?.url,
    ].filter(Boolean);
    await saveResult(event.request_id, urls); // copy files to your storage now
  } else {
    await markFailed(event.request_id, event.error ?? event.payload_error);
  }
});