Webhooks

POST /hooks/kinoseed HTTP/1.1
Content-Type: application/json
Kinoseed-Signature: t=1793000000,v1=5f2b...e41a
Kinoseed-Event-Id: evt_8c1d0b6e4f2a4e9b9a3c7d5e1f0a2b3c
Kinoseed-Event-Type: job.completed

{
  "id": "evt_8c1d0b6e4f2a4e9b9a3c7d5e1f0a2b3c",
  "type": "job.completed",
  "createdAt": "2026-10-25T18:02:11.000Z",
  "data": {
    "id": "JOB_ID",
    "kind": "image",
    "status": "completed",
    "progress": 100,
    "model": "nano-banana-pro",
    "prompt": "a ceramic mug on a sunlit desk, product photo",
    "credits": { "charged": 4, "refunded": 0 },
    "output": { "videoUrl": null, "imageUrls": ["https://..."], "thumbUrl": "https://..." },
    "error": null,
    "metadata": { "order": "1042" },
    "createdAt": "2026-10-25T18:01:40.000Z",
    "completedAt": "2026-10-25T18:02:09.000Z",
    "links": { "self": "https://kinoseed.app/api/v1/jobs/JOB_ID", "web": "https://kinoseed.app/library" }
  }
}

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

const SECRET = process.env.KINOSEED_WEBHOOK_SECRET!; // whsec_..., from POST /webhooks
const TOLERANCE_SECONDS = 5 * 60;

export function verifyKinoseedSignature(rawBody: string, header: string | null): boolean {
  if (!header) return false;
  const parts = new Map(
    header.split(",").map((p): [string, string] => {
      const i = p.indexOf("=");
      return [p.slice(0, i).trim(), p.slice(i + 1).trim()];
    }),
  );
  const t = Number(parts.get("t"));
  const v1 = parts.get("v1");
  if (!Number.isInteger(t) || !v1) return false;
  if (Math.abs(Date.now() / 1000 - t) > TOLERANCE_SECONDS) return false;
  const expected = createHmac("sha256", SECRET).update(`${t}.${rawBody}`).digest();
  const given = Buffer.from(v1, "hex");
  return given.length === expected.length && timingSafeEqual(given, expected);
}

// A Next.js route handler. Read the raw text first: the signature covers the
// exact bytes, so parse JSON only after it checks out.
export async function POST(req: Request) {
  const raw = await req.text();
  if (!verifyKinoseedSignature(raw, req.headers.get("kinoseed-signature"))) {
    return new Response("bad signature", { status: 400 });
  }
  const event = JSON.parse(raw); // { id, type, createdAt, data: Job }
  // Deliveries can repeat: skip an event.id you have already handled.
  if (event.type === "job.completed") console.log(event.data.id, event.data.output);
  if (event.type === "job.failed") console.log(event.data.id, event.data.error);
  return new Response(null, { status: 204 });
}