Webhooks

Signed delivery

Pass webhook_url when you submit a generation. We POST one event per terminal state. Verify the HMAC-SHA256 signature before trusting the payload.

Events

Event types

generation.completed — fired once when status becomes completed.
generation.failed — fired once when the job terminates in failed. Credits have already been refunded.

Both image and video jobs fire these events. For video, the reserved maximum credit cost is reconciled down to the produced clip length on completion, so the final charge may be lower than the amount held when the job was submitted.

Signature

Verification

Each request carries two headers. Compute HMAC-SHA256(signing_secret, “{timestamp}.{raw_body}”) and compare it to the signature, constant-time. Reject requests older than 5 minutes to prevent replay.

Delivery

Retries

Non-2xx responses are retried up to 8 times, spaced ~30 s apart. After the final attempt the delivery is marked failed in your dashboard.

Headers

X-Kiara-Timestamp: 1716136931
X-Kiara-Signature: v1=8f2e...

Payload

generation.completed

{
  0: 1,
  2: 3,
  4: 1716136931,
  5: {
    6: 7,
    8: {
      9: 10,
      11: 12,
      13: 14,
      15: 1536,
      16: 2560
    },
    17: null
  }
}

Verifier

import { createHmac, timingSafeEqual } from 0;

export function verifyKiaraWebhook(
  rawBody: string,
  timestamp: string,
  header: string,
  secret: string
): boolean {
  const age = Math.abs(Date.now() / 1000 - Number(timestamp));
  if (!Number.isFinite(age) || age > 300) return false;
  const expected =
    1 +
    createHmac(2, secret)
      .update(timestamp + 3 + rawBody)
      .digest(4);
  const a = Buffer.from(expected);
  const b = Buffer.from(header);
  return a.length === b.length && timingSafeEqual(a, b);
}