Guides
Webhooks
Instead of polling, let Lokki call you when something happens: a market's video is ready, waiting for approval, live on TikTok, or failed. Every request is signed with your webhook's secret.
Create a webhook#
bash
curl -X POST "https://uselokki.com/api/v1/webhooks" -H "Authorization: Bearer $LOKKI_KEY" \
-H "Content-Type: application/json" \
-d '{"url": "https://example.com/hooks/lokki", "events": ["variant.pending_approval", "variant.published", "variant.failed"]}'The response contains secret (whsec_…) once — store it. Use ["*"] to receive every event. Needs a key with webhooks:write (or an admin in Settings → Webhooks, where you can also send a test ping).
Events#
| Event | When |
|---|---|
variant.localized | Text for a market is ready (AI, your override or source). |
variant.rendered | The video and thumbnail for a market are rendered — ready for review. |
variant.pending_approval | Submitted; waiting for a person (or your approver key). |
variant.approved | Approved; will publish at its scheduled time. |
variant.rejected | Rejected; data.error holds the reason. |
variant.published | Live on TikTok; data.post_url is the public link. |
variant.failed | Localization, rendering or publishing failed; data.error explains. |
boost.proposed | A winner was found and a Spark Ads boost is proposed (needs approval). |
comment.received | A new comment arrived on one of your videos. |
Payload#
Lokki sends a POST with a JSON body:
json
{
"id": "whd_8Kq2Lm0Zx7Pw1A",
"type": "variant.published",
"created_at": "2026-11-17T18:00:04.512Z",
"data": {
"variant_id": "var_de9Fk2LmQx81",
"post_id": "post_7f3k2Qx9Lm2Ab",
"market_id": "mkt_de4Gh7Ns2Kd",
"language": "de",
"status": "published",
"post_url": "https://www.tiktok.com/@wildcamp.de/video/7412345678901234567",
"error": null
}
}idis unique per delivery — use it to ignore duplicates (a retry has the sameid).typeis the event;dataforvariant.*events hasvariant_id,post_id,market_id,language,status,post_urlanderror.- Fetch
GET /api/v1/variants/:variant_idfor the full, current state — events can arrive out of order.
Verify the signature#
Each request has a header
http
Lokki-Signature: t=1795000004,v1=Zq3k…base64url…where v1 = base64url( HMAC-SHA256( secret, t + "." + rawBody ) ) — the timestamp, a dot, and the raw request body exactly as received. Compute it, compare in constant time, and reject timestamps older than 5 minutes (replay protection).
js
import crypto from "node:crypto";
import express from "express";
const app = express();
app.post("/hooks/lokki", express.raw({ type: "application/json" }), (req, res) => {
const header = req.get("Lokki-Signature") ?? "";
const { t, v1 } = Object.fromEntries(header.split(",").map((p) => p.split("=")));
const expected = crypto.createHmac("sha256", process.env.LOKKI_WEBHOOK_SECRET)
.update(`${t}.${req.body}`).digest("base64url");
const fresh = Math.abs(Date.now() / 1000 - Number(t)) < 300;
const valid = v1 && v1.length === expected.length && crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected));
if (!fresh || !valid) return res.status(400).send("bad signature");
const event = JSON.parse(req.body);
// de-duplicate on event.id, then queue your work
res.sendStatus(200);
});python
import base64, hashlib, hmac, json, os, time
from flask import Flask, request, abort
app = Flask(__name__)
SECRET = os.environ["LOKKI_WEBHOOK_SECRET"].encode()
@app.post("/hooks/lokki")
def lokki_hook():
raw = request.get_data() # raw bytes, before any JSON parsing
parts = dict(p.split("=", 1) for p in request.headers.get("Lokki-Signature", "").split(","))
t, v1 = parts.get("t", "0"), parts.get("v1", "")
mac = hmac.new(SECRET, f"{t}.".encode() + raw, hashlib.sha256).digest()
expected = base64.urlsafe_b64encode(mac).rstrip(b"=").decode()
if abs(time.time() - int(t)) > 300 or not hmac.compare_digest(v1, expected):
abort(400)
event = json.loads(raw)
# de-duplicate on event["id"], then queue your work
return "", 200Use the raw body
Verify against the bytes you received. Re-serialising parsed JSON changes whitespace and key order, and the signature won't match. base64url has no= padding.Delivery and retries#
- Respond with any
2xxquickly (within ~10 s); do the work asynchronously. - Non-2xx responses, timeouts and connection errors are retried with exponential backoff (up to 6 attempts in total). After that the delivery is marked failed; you can see recent deliveries in Settings → Webhooks.
- Deliveries are at-least-once and not ordered: de-duplicate on
idand treatstatusin the payload (or a freshGET) as the truth. - Webhooks are per workspace. Delete one with
DELETE /webhooks/:id.