Вебхуки

Передайте webhook_url при отправке генерации, и когда задача завершится, Clipia отправит POST на этот адрес. Так не нужно опрашивать статус. Каждая доставка подписана HMAC-SHA256 секретом вашего ключа, а при сбое повторяется в течение примерно суток.

Требования к адресуСкопировать ссылку на раздел

• Только https://. Адреса во внутренних и частных сетях отклоняются при отправке с ошибкой 400 webhook_url_invalid.
• Редиректы не выполняются: ответ 3xx считается неуспешной доставкой.

Тело запросаСкопировать ссылку на раздел

Успех:

{
  "request_id": "764cabcf-b745-4b3e-ae38-1200304cf45b",
  "status": "OK",
  "payload": {
    "model": "nano-banana-2",
    "output": { "images": [{ "url": "https://media.clipia.ai/....webp" }] },
    "cost": 12
  }
}

Ошибка генерации:

{
  "request_id": "764cabcf-b745-4b3e-ae38-1200304cf45b",
  "status": "ERROR",
  "error": {
    "code": "generation_failed",
    "message": "Generation failed. Please retry or contact support."
  }
}

output зависит от типа модели: images: [{ url }], video: { url } или audio: { url, format? } вместе с audios: [{ url, format? }] (все варианты трека, первый совпадает с audio). error.code — из словаря ошибок генерации: generation_failed, content_moderated, model_unavailable и другие; незнакомый код обрабатывайте как generation_failed.

ЗаголовкиСкопировать ссылку на раздел

Content-Type: application/json
X-Clipia-Webhook-Id: 1f2e3d4c-5b6a-7890-abcd-ef0123456789
X-Clipia-Timestamp: 1760011200
X-Clipia-Signature: t=1760011200,v1=5257a869e7...

Секрет подписиСкопировать ссылку на раздел

Секрет свой у каждого API-ключа: вебхуки задач, отправленных этим ключом, подписываются им. Секрет показывается один раз при создании ключа в консоли разработчика. Истории доставок и повторной отправки в консоли нет. Если секрет потерян, создайте новый ключ и переключите на него интеграцию — см. «Управление ключами».

Проверка подписиСкопировать ссылку на раздел

Подпись считается как HMAC_SHA256(secret, "{timestamp}.{raw_body}"). Проверяйте её по сырому телу запроса, до разбора JSON, сравнивайте в постоянном времени и отклоняйте доставки старше 5 минут. Проще всего взять готовую функцию из SDK.

import { verifyWebhookSignature } from 'clipia-ai/webhook';

// rawBody — исходные байты тела, не JSON.stringify(req.body)
const ok = verifyWebhookSignature({
  secret: process.env.CLIPIA_WEBHOOK_SECRET!,
  headers: req.headers,
  body: rawBody,
  toleranceSeconds: 300,
});
if (!ok) return res.status(401).end();

Обе функции SDK возвращают true или false и не бросают исключений на испорченных заголовках.

Доставка и повторыСкопировать ссылку на раздел

• Отвечайте кодом 2xx в течение 10 секунд. Тяжёлую обработку выполняйте после ответа.
• Ответ не 2xx, 3xx или таймаут считаются неуспехом. Доставка повторяется до 15 попыток в сумме.
• Пауза между попытками растёт вдвое, начиная с 30 секунд, и не превышает 4 часов: 30 с, 1, 2, 4, 8, 16, 32 мин, 1 ч 04 мин, 2 ч 08 мин, затем по 4 часа — всего около 24 часов 15 минут с первой попытки. Отправка проверяется раз в 30 секунд, поэтому фактическая задержка может быть немного больше.
• После последней неудачи доставка помечается проваленной и больше не повторяется; запросить её заново нельзя. Если обработчик лежал дольше, заберите результат по GET /v1/requests/:id — он хранится независимо от вебхука.

В тестовом режиме вебхук тоже приходит и подписан так же — на нём удобно проверить обработчик. Тестовому ключу отправляется не больше одной доставки в минуту: остальные за эту минуту не создаются, а неудачная доставка повторяется не дальше трёх попыток.