☰ Menu

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#

EventWhen
variant.localizedText for a market is ready (AI, your override or source).
variant.renderedThe video and thumbnail for a market are rendered — ready for review.
variant.pending_approvalSubmitted; waiting for a person (or your approver key).
variant.approvedApproved; will publish at its scheduled time.
variant.rejectedRejected; data.error holds the reason.
variant.publishedLive on TikTok; data.post_url is the public link.
variant.failedLocalization, rendering or publishing failed; data.error explains.
boost.proposedA winner was found and a Spark Ads boost is proposed (needs approval).
comment.receivedA 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
  }
}
  • id is unique per delivery — use it to ignore duplicates (a retry has the same id).
  • type is the event; data for variant.* events has variant_id, post_id, market_id, language, status, post_url and error.
  • Fetch GET /api/v1/variants/:variant_id for 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);
});

Use 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 2xx quickly (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 id and treat status in the payload (or a fresh GET) as the truth.
  • Webhooks are per workspace. Delete one with DELETE /webhooks/:id.