Руководства

Вебхуки

Мы сообщим на ваш адрес, когда видео закончится. Опрашивать статус не придётся.

Пока эмулируется. Адреса сохраняются, события пишутся в журнал на странице «Вебхуки», но запрос на ваш адрес ещё не уходит. Ниже описан формат, который заработает вместе с рендером.

События

Событие	Когда
`video.succeeded`	Видео готово, ссылка в data.output.url
`video.failed`	Ошибка рендера или отказ по правилам, токены вернулись
`video.canceled`	Видео отменено, токены вернулись

Что придёт

POST с JSON. В data лежит тот же объект, что отдаёт GET /v1/videos/{id}.

{
  "type": "video.succeeded",
  "created_at": "2026-11-02T12:04:12.000Z",
  "data": {
    "id": "vid_8fK2mQxLp0ZrT4nYw7Vb1sDc",
    "object": "video",
    "status": "succeeded",
    "output": { "url": "https://…mp4", "poster_url": "https://…jpg", "expires_at": "…" },
    "metadata": { "order_id": "4815" }
  }
}

Как проверить подпись

Заголовок Hawklance-Signature содержит время и подпись: t=1793190000,v1=5f8a…. Подпись — HMAC-SHA256 от строки {t}.{тело запроса} на секрете адреса. Секрет показывается один раз при создании адреса и начинается с whsec_. Считайте подпись по исходному телу, до разбора JSON.

Node.js

import { createHmac, timingSafeEqual } from "node:crypto";

function verify(rawBody, header, secret) {
  const { t, v1 } = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false; // старше 5 минут
  const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  return timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}

Python

import hashlib, hmac, time

def verify(raw_body: bytes, header: str, secret: str) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    if abs(time.time() - int(parts["t"])) > 300:  # старше 5 минут
        return False
    signed = f"{parts['t']}.".encode() + raw_body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts["v1"])

Как отвечать

Ответьте кодом 2xx в течение 10 секунд, долгую работу делайте после ответа.
Если адрес не ответил, повторим с растущей паузой в течение суток.
Одно событие может прийти дважды: проверяйте по data.id, что уже обработали.