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"
}
]
}
}| type | When |
|---|---|
generation.succeeded | The result is ready. Its files are kept for 30 days, until each output's expires_at. |
generation.failed | The order failed and nothing was charged. data.error says why. |
ping | Only 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.succeededlater for the same order, at no charge. idis the delivery's id and stays the same on every retry. Use it to skip an event you have already handled.
Headers
| Header | Value |
|---|---|
X-TikiAPI-Event | The type, e.g. generation.succeeded. |
X-TikiAPI-Delivery | The event id. |
X-TikiAPI-Signature | t=1794736931,v1=5f2a…: the time it was signed (Unix seconds) and the signature. |
User-Agent | TikiAPI-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:
- Take the raw body bytes as they arrived, before any JSON parsing.
- Compute HMAC-SHA256 of
t, a dot and the body, with your secret, as hex. - Compare it with
v1in constant time, and reject events whosetis 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 "", 200Answer 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.
