От задачи
до интеграции.

Webhook завершения задач

Опциональная доставка на HTTPS-адрес из настроек проекта. По умолчанию внешняя отправка выключена; её включение согласуется отдельно. До включения используйте опрос статуса. Подготовка адреса не открывает платный доступ.

POST JSON. Типы: job.succeeded, job.failed, job.cancelled; бесплатная проверка — webhook.test. Поля: id, type, createdAt, data. Для задачи data содержит id, model, status, chargedRub, chargedCredits, statusUrl. В тесте data равно {"test":true}.

Промпт, файл и данные аккаунта не входят в событие. За результатом обращайтесь к statusUrl с API-ключом, затем скачивайте приватный result.url. Не считайте уведомление о завершении гарантией доступности файла после срока хранения.

Подпись: X-Prelusion-Signature: t=UNIX_SECONDS,v1=HEX. HMAC-SHA256 от timestamp + '.' + rawBody, ключ — отдельный секрет webhook, не API-ключ. Проверяйте исходные байты, отклоняйте отклонение времени более 5 минут в любую сторону. Синхронизируйте часы сервера. Пример проверки на Python:

import hashlib, hmac, time

def verify_webhook(secret, signature, raw_body):
    fields = dict(part.split("=", 1) for part in signature.split(","))
    timestamp = fields["t"]
    if abs(time.time() - int(timestamp)) > 300:
        raise ValueError("Expired signature")
    signed = timestamp.encode("ascii") + b"." + raw_body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected, fields["v1"]):
        raise ValueError("Invalid signature")
    # Parse JSON only after verification. Deduplicate event ID in your database.
    return True

Неверный формат заголовка тоже отклоняйте (ошибка 400/401). После проверки подписи сохраняйте event ID и принятую задачу транзакционно, затем отвечайте 2xx. Заголовок X-Prelusion-Event-Id совпадает с id тела. Повтор с тем же id не должен повторять вашу бизнес-операцию.

Доставка допускает дубли: стабильный event ID, новая подпись при каждой попытке. До 8 попыток за 72 часа; паузы 1, 5, 15 минут, 1, 3, 6 и 12 часов. После ответа 2xx повторы прекращаются. Ошибки, таймауты и 3xx вызывают повтор; перенаправления не выполняются. Журнал хранится 30 дней после создания события. Финансовый итог и генерация от доставки не зависят.

Только публичный HTTPS, порт 443, без логина, пароля, query и fragment. DNS проверяется перед каждой попыткой. Смена адреса, секрета или переключателя отменяет старую очередь, но уже отправленный запрос отозвать нельзя. Новая настройка не пересылает старые завершённые задачи. Пропущенное событие восстанавливайте опросом статуса, не повторным запуском генерации.