Skip to contentLaunch price until December 31 · 45 days left

Webhooks

A POST to your server when an order is done, so you don't have to keep asking.

Set it up

Open Webhooks in the dashboard, enter your URL under Endpoint and save it. Every order of the account is then reported there. Under Signing secret, reveal and copy the secret you check signatures with; "Roll the secret" makes a new one if the old one leaks. To send one order somewhere else, give it a webhook_url: it wins over the account's.

curl https://api.tikiapi.com/v1/generations \
  -H "Authorization: Bearer $TIKIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.5",
    "prompt": "A paper boat drifts down a rainy street",
    "duration": 10,
    "webhook_url": "https://example.com/hooks/tikiapi"
  }'

The URL must be public https on the default port, with a host name (no IP address) and no login in it. Anything else is refused with 400 invalid_parameter when you create the order.

What we send

A POST with a JSON body. data is the order exactly as GET /v1/generations/:id returns it.

{
  "id": "evt_01a1d6f2c3b44e0f9d1a7c55e2b0a913",
  "type": "generation.succeeded",
  "created_at": "2026-11-15T10:02:11.000Z",
  "data": {
    "id": "01a1d505-9092-76d6-aa18-ec5b3f2a65c6",
    "status": "succeeded",
    "price": "0.84",
    "outputs": [
      {
        "url": "https://cdn.tikiapi.com/api/…/video.mp4",
        "content_type": "video/mp4",
        "expires_at": "2026-12-15T10:02:11.000Z"
      }
    ]
  }
}
typeWhen
generation.succeededThe result is ready. Its files are kept for 30 days, until each output's expires_at.
generation.failedThe order failed and nothing was charged. data.error says why.
pingOnly from the "Send test event" button on the Webhooks page, to check your endpoint: the page shows the status your server answered. data is { "account_id": "…" }. Not retried.
  • Orders made with a test key send events too, so you can build the whole flow for free.
  • A canceled order sends nothing: you canceled it.
  • A result can come after an order has failed. Then you get generation.succeeded later for the same order, at no charge.
  • id is the delivery's id and stays the same on every retry. Use it to skip an event you have already handled.

Headers

HeaderValue
X-TikiAPI-EventThe type, e.g. generation.succeeded.
X-TikiAPI-DeliveryThe event id.
X-TikiAPI-Signaturet=1794736931,v1=5f2a…: the time it was signed (Unix seconds) and the signature.
User-AgentTikiAPI-Webhooks/1.0

Check the signature

Every event is signed with your webhook secret, so you know it came from us. v1 is the hex HMAC-SHA256 of <t>.<raw body>. To check it:

  1. Take the raw body bytes as they arrived, before any JSON parsing.
  2. Compute HMAC-SHA256 of t, a dot and the body, with your secret, as hex.
  3. Compare it with v1 in constant time, and reject events whose t is more than 5 minutes old.
import crypto from "node:crypto";
import express from "express";

const app = express();

app.post("/hooks/tikiapi", express.raw({ type: "application/json" }), (req, res) => {
  const header = req.get("X-TikiAPI-Signature") ?? "";
  const { t, v1 } = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const expected = crypto
    .createHmac("sha256", process.env.TIKIAPI_WEBHOOK_SECRET)
    .update(`${t}.${req.body}`)
    .digest("hex");
  const fresh = Math.abs(Date.now() / 1000 - Number(t)) < 300;
  const valid =
    fresh &&
    expected.length === (v1 ?? "").length &&
    crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
  if (!valid) return res.sendStatus(400);

  const event = JSON.parse(req.body);
  res.sendStatus(200); // answer first, then do the work
  handle(event);
});
import hashlib, hmac, os, time
from flask import Flask, request, abort

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

@app.post("/hooks/tikiapi")
def tikiapi():
    parts = dict(p.split("=", 1) for p in request.headers.get("X-TikiAPI-Signature", "").split(","))
    t, v1 = parts.get("t", "0"), parts.get("v1", "")
    expected = hmac.new(SECRET, f"{t}.".encode() + request.get_data(), hashlib.sha256).hexdigest()
    if abs(time.time() - int(t)) > 300 or not hmac.compare_digest(expected, v1):
        abort(400)
    event = request.get_json()
    handle(event)
    return "", 200

Answer and retries

Reply with any 2xx within 10 seconds and the event is delivered. Redirects aren't followed. Anything else, or no answer in time, is a failed try, and we try again after 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours, 12 hours: seven tries in all. Deliveries on the Webhooks page lists every event with its status (Delivered, Retrying or Gave up), the tries and your server's answer. Resend an undelivered one from there once your endpoint is fixed.

Answer first and do slow work after, so a long download doesn't time out the delivery. Webhooks don't replace the API: you can always read an order with GET /v1/generations/:id.

NextModels