Task webhooks

Add a webhook field when you submit an asynchronous task. When the task finishes (succeeds or fails), SnapGen POSTs the result to your URL. No registration, no extra credentials — just your API key.

Quick start

curl https://api.snapgen.org/v1/videos \
  -H "Authorization: Bearer $SNAPGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-omni-t2v",
    "prompt": "A paper airplane glides through a sunlit library",
    "seconds": "10",
    "webhook": "https://your-server.com/snapgen/callback",
    "webhook_secret": "your-random-secret"
  }'

webhook_secret is optional — it makes deliveries HMAC-signed so you can verify them. We POST to exactly the URL you provide. Webhooks fire only on final states (completed / failed) — never while the task is still running.

What you receive

The POST body is identical to the Get task status response — one parser handles both:

{
  "id": "task_01HXYZ",
  "object": "task",
  "status": "completed",
  "model": "gemini-omni-t2v",
  "progress": 100,
  "created": 1784324432,
  "completed": 1784324660,
  "cost": 0.25,
  "result": {
    "videos": [
      {
        "url": ["https://storage.example.com/videos/output.mp4"],
        "expires_at": 1785534260
      }
    ]
  },
  "error": null
}

Failed tasks arrive with "status": "failed", "result": null, and error.message — they are automatically refunded.

Retries and deduplication

Respond with any 2xx within 10 seconds. Acknowledge first, process asynchronously.
No 2xx (timeout or 5xx): we retry after 10s, 30s, 60s, then 5m, 30m, and 2h — about three hours in total, so a deploy window or short outage on your side doesn’t lose the notification.
A 4xx response means your address rejected the request — we stop immediately, no retries.
In rare cases you may receive the same notification twice. Deduplicate on id + status.
Webhooks are an optimization, not the source of truth: if all retries are exhausted, GET /v1/tasks/{id} still has the result. Keep a reconciliation poll for tasks you haven’t heard back about.

Webhook URL requirements

Requirement	Detail
Publicly reachable	Internal/private addresses (`127.0.0.1`, `10.x`, `192.168.x`, …) are rejected at submit time.
Protocol	`http` or `https` (use `https` in production).
Not our domain	URLs pointing at `snapgen.org` are rejected.

An invalid webhook value fails the submission with an invalid_request error — fix the URL and resubmit.

Developing locally? Private addresses can’t receive webhooks — expose your handler with a tunnel (for example cloudflared tunnel or ngrok http 3000) and use the tunnel URL, or just poll GET /v1/tasks/{id} during development.

Verifying authenticity

Two options, from simplest to strongest: Option 1 — re-fetch (no secret needed). Treat the callback as a notification and confirm the result with the source of truth: fetch GET /v1/tasks/{id} using your own API key before acting on it. A forged callback cannot survive that check. Option 2 — signed webhooks. Pass a webhook_secret (8–128 characters, you choose it) alongside webhook when submitting:

{ "webhook": "https://your-server.com/callback", "webhook_secret": "your-random-secret" }

Deliveries for that task then carry an X-Shim-Signature: t=<unix seconds>,v1=<hex> header, where v1 = HMAC-SHA256(webhook_secret, "<t>.<raw request body>"). Compute over the raw body bytes and reject timestamps older than five minutes:

const crypto = require("node:crypto");

function verifyWebhook(secret, rawBody, header, toleranceSec = 300) {
  const parts = Object.fromEntries(
    header.split(",").map((p) => p.split("=", 2)),
  );
  if (Math.abs(Date.now() / 1000 - Number(parts.t)) > toleranceSec) return false;
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${parts.t}.${rawBody}`)
    .digest("hex");
  const given = Buffer.from(parts.v1 ?? "");
  return (
    given.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(expected), given)
  );
}

import hashlib
import hmac
import time


def verify_webhook(secret, raw_body, signature_header, tolerance_sec=300):
    parts = dict(p.split("=", 1) for p in signature_header.split(","))
    if abs(time.time() - int(parts["t"])) > tolerance_sec:
        return False
    expected = hmac.new(
        secret.encode(),
        f"{parts['t']}.{raw_body}".encode(),
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(expected, parts.get("v1", ""))

Minimal receiver

const http = require("node:http");

http.createServer((req, res) => {
  let body = "";
  req.on("data", (chunk) => (body += chunk));
  req.on("end", () => {
    res.writeHead(200).end("ok"); // acknowledge first
    const task = JSON.parse(body);
    console.log("task finished:", task.id, task.status);
    // dedupe on task.id + task.status, then confirm via GET /v1/tasks/{id}
  });
}).listen(3000);

from http.server import BaseHTTPRequestHandler, HTTPServer
import json

class Handler(BaseHTTPRequestHandler):
    def do_POST(self):
        length = int(self.headers.get("Content-Length") or 0)
        task = json.loads(self.rfile.read(length))
        self.send_response(200)
        self.end_headers()  # acknowledge first
        print("task finished:", task["id"], task["status"])
        # dedupe on id + status, then confirm via GET /v1/tasks/{id}

HTTPServer(("0.0.0.0", 3000), Handler).serve_forever()

FAQ

I submitted with a webhook but received nothing

Check, in order: (1) has the task actually finished? Fetch GET /v1/tasks/{id} — webhooks only fire on completed/failed; (2) is your URL publicly reachable from the internet; (3) does your endpoint return 2xx within 10 seconds — a 4xx stops delivery permanently.

Why is result.videos[].url an array?

Some models return multiple files per task. Handle it as an array even when it contains one URL.

How long do result links work?

Until expires_at (media is retained for 14 days). Download the files to your own storage promptly.

Do webhooks replace polling?

Polling stays fully supported. Webhooks are an optimization — if a delivery is missed, GET /v1/tasks/{id} always has the latest state. For anything critical, keep a reconciliation poll as the fallback.

Can I receive webhooks on localhost?

No — private addresses are rejected for security. Use a tunnel (cloudflared, ngrok) during development, or poll instead.

Overview

Text Series

Image Series

Video Series

Endpoint Reference

Task Management

Quick start

What you receive

Retries and deduplication

Webhook URL requirements

Verifying authenticity

Minimal receiver

FAQ

​Quick start

​What you receive

​Retries and deduplication

​Webhook URL requirements

​Verifying authenticity

​Minimal receiver

​FAQ

Quick start

What you receive

Retries and deduplication

Webhook URL requirements

Verifying authenticity

Minimal receiver

FAQ