Webhook

Invece del polling, passa webhook_url quando invii una generazione. Quando il job raggiunge uno stato finale, inviamo a quell’URL una richiesta HTTPS POST con l’intero oggetto di generazione, firmata con il segreto del tuo account.

Richiedere un webhook#

Aggiungi webhook_url al corpo di qualsiasi richiesta POST /api/v1/run/{endpoint}. Deve essere un URL HTTPS raggiungibile da Internet.

curl -X POST https://cheapergen.com/api/v1/run/bytedance/seedance-2.0-fast/text-to-video \
  -H "Authorization: Bearer $CHEAPERGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "prompt": "Lento avvicinamento a un ceramista che modella un vaso all’ora dorata, polvere sospesa nella luce, profondità di campo ridotta",
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "duration": 5,
  "webhook_url": "https://your-app.com/hooks/cheapergen"
}'

Eventi#

Le generazioni annullate non attivano un webhook: le hai annullate tu, quindi lo sai già.

Payload#

Il corpo è JSON e include l’evento type e la generazione in data — lo stesso oggetto restituito da GET /generations/{id}.

{
  "type": "generation.succeeded",
  "data": {
    "id": "gen_8c2QmX1nq0k4Lw7Z",
    "object": "generation",
    "model": "bytedance/seedance-2.0-fast",
    "endpoint": "bytedance/seedance-2.0-fast/text-to-video",
    "mode": "text-to-video",
    "status": "succeeded",
    "input": {
      "prompt": "Lento avvicinamento a un ceramista che modella un vaso all’ora dorata, polvere sospesa nella luce, profondità di campo ridotta",
      "aspect_ratio": "16:9",
      "resolution": "720p",
      "duration": 5,
      "generate_audio": true
    },
    "output": {
      "video": {
        "url": "https://cdn.cheapergen.com/outputs/gen_8c2QmX1nq0k4Lw7Z.mp4",
        "content_type": "video/mp4"
      }
    },
    "error": null,
    "cost": {
      "amount_usd": 0.4494,
      "currency": "usd",
      "estimated": false
    },
    "source": "api",
    "created_at": "2026-10-15T09:21:04.512Z",
    "started_at": "2026-10-15T09:21:09.031Z",
    "completed_at": "2026-10-15T09:22:31.870Z",
    "retention": "1d",
    "expires_at": "2026-10-16T09:22:31.870Z",
    "purged_at": null
  }
}

Intestazioni#

Verificare le firme#

Verifica sempre la firma prima di fidarti di un webhook: chiunque può inviare una richiesta POST a un URL pubblico. L'intestazione ha questo formato:

CheaperGen-Signature: t=1760520151,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

1. Separa l’header in corrispondenza di , e leggi i valori di t (timestamp) e v1 (firma).
2. Crea la stringa da firmare: il timestamp, un carattere . letterale e poi corpo grezzo della richiesta esattamente come ricevuto.
3. Calcola l'HMAC-SHA256 della stringa usando il segreto di firma come chiave e convertilo in esadecimale.
4. Confrontalo con v1 usando un confronto a tempo costante e rifiuta i timestamp più vecchi di alcuni minuti per impedire i replay.

Il tuo segreto di firma inizia con whsec_ ed è mostrato nella dashboard accanto alle chiavi API. Conservalo lato server, come una chiave API.

Il tuo codice può anche recuperarlo con una chiave API: GET /api/v1/webhooks/secret restituisce { "key": "whsec_…" }. Se l’account non ha ancora un segreto, la prima chiamata lo crea.

curl https://cheapergen.com/api/v1/webhooks/secret \
  -H "Authorization: Bearer $CHEAPERGEN_API_KEY"

Node.js#

import crypto from "node:crypto";

const TOLERANCE_SECONDS = 300; // reject deliveries older than 5 minutes

/**
 * Verify a CheaperGen webhook.
 * @param rawBody  the request body exactly as received (string or Buffer) — not re-serialized JSON
 * @param header   the value of the "CheaperGen-Signature" header
 * @param secret   your signing secret (whsec_…)
 */
export function verifyCheaperGenSignature(rawBody, header, secret) {
  const parts = Object.fromEntries(
    String(header ?? "")
      .split(",")
      .map((kv) => kv.trim().split("=", 2)),
  );
  const t = Number(parts.t);
  const v1 = parts.v1;
  if (!Number.isFinite(t) || !v1) return false;
  if (Math.abs(Date.now() / 1000 - t) > TOLERANCE_SECONDS) return false;

  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${t}.${rawBody}`)
    .digest("hex");

  const a = Buffer.from(expected, "hex");
  const b = Buffer.from(v1, "hex");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

// app/api/hooks/cheapergen/route.ts (Next.js App Router)
import { verifyCheaperGenSignature } from "@/lib/cheapergen";

export async function POST(req: Request) {
  const raw = await req.text(); // raw body — do not call req.json() first
  const ok = verifyCheaperGenSignature(raw, req.headers.get("cheapergen-signature"), process.env.CHEAPERGEN_WEBHOOK_SECRET!);
  if (!ok) return new Response("invalid signature", { status: 400 });

  const event = JSON.parse(raw);
  // Acknowledge fast; do heavy work (downloads, DB writes) in a queue.
  await enqueue(event); // your code
  return new Response(null, { status: 204 });
}

import express from "express";
import { verifyCheaperGenSignature } from "./cheapergen.js";

const app = express();

// Use the raw body for this route only.
app.post("/hooks/cheapergen", express.raw({ type: "application/json" }), (req, res) => {
  const ok = verifyCheaperGenSignature(req.body.toString("utf8"), req.get("CheaperGen-Signature"), process.env.CHEAPERGEN_WEBHOOK_SECRET);
  if (!ok) return res.status(400).send("invalid signature");

  const event = JSON.parse(req.body.toString("utf8"));
  if (event.type === "generation.succeeded") {
    console.log("done:", event.data.id, event.data.output);
  } else if (event.type === "generation.failed") {
    console.log("failed:", event.data.id, event.data.error);
  }
  res.sendStatus(204);
});

Python#

import hashlib, hmac, time

TOLERANCE_SECONDS = 300  # reject deliveries older than 5 minutes

def verify_cheapergen_signature(raw_body: bytes, header: str, secret: str) -> bool:
    """Verify a CheaperGen webhook. raw_body must be the exact bytes received."""
    try:
        parts = dict(kv.strip().split("=", 1) for kv in (header or "").split(","))
        t, v1 = int(parts["t"]), parts["v1"]
    except (KeyError, ValueError):
        return False
    if abs(time.time() - t) > TOLERANCE_SECONDS:
        return False
    signed = f"{t}.".encode() + raw_body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, v1)

import json, os
from flask import Flask, request, abort

app = Flask(__name__)
SECRET = os.environ["CHEAPERGEN_WEBHOOK_SECRET"]

@app.post("/hooks/cheapergen")
def cheapergen_webhook():
    raw = request.get_data()  # raw bytes, before any JSON parsing
    if not verify_cheapergen_signature(raw, request.headers.get("CheaperGen-Signature", ""), SECRET):
        abort(400)
    event = json.loads(raw)
    if event["type"] == "generation.succeeded":
        print("done:", event["data"]["id"], event["data"]["output"])
    else:
        print("failed:", event["data"]["id"], event["data"]["error"])
    return "", 204

Consegna e nuovi tentativi#

• Rispondi con qualsiasi stato 2xx entro 10 secondi per confermare la consegna. I reindirizzamenti non vengono seguiti.
• Se il tuo endpoint va in timeout o risponde con qualcosa di diverso da 2xx, riproviamo per un massimo di un’ora: circa 1, 3, 8, 18, 38 e 60 minuti dopo il primo tentativo (7 tentativi in tutto), poi ci fermiamo. Una risposta 410 Gone interrompe subito i tentativi.
• Ogni tentativo viene firmato di nuovo con un t nuovo, quindi un nuovo tentativo supera il controllo dei 5 minuti come la prima consegna.
• Le consegne possono arrivare più di una volta e, raramente, fuori ordine. Rendi il tuo handler idempotente: usa come chiave l’header CheaperGen-Webhook-Id (uguale a ogni nuovo tentativo di una notifica) e ignora le notifiche già elaborate.
• I webhook inviano notifiche, ma non sono l’unica fonte attendibile. Se te ne perdi uno, la generazione è sempre disponibile tramite GET /api/v1/generations/{id}; una riconciliazione periodica dei job ancora in sospeso sul tuo lato copre ogni caso limite.

Test in locale#

Gli URL dei webhook devono essere raggiungibili pubblicamente tramite HTTPS. Durante lo sviluppo, esponi il server locale con un tunnel (per esempio cloudflared tunnel o ngrok http 3000) e usa l’URL HTTPS del tunnel come webhook_url.