Webhooks
Уведомления о завершении задач
Базовый адрес — https://api.iskragen.ru. Общие правила — в обзоре справочника.
GET /v1/webhook-endpoints/
Список webhook-endpoint'ов. Возвращает свои endpoint'ы от новых к старым с полями active, failureCount, lastDeliveryAt; секрет не возвращается. Требуется API-ключ; действует общий лимит 60 запросов в минуту, превышение возвращает 429 RATE_LIMIT_ERROR с retryAfter, а отсутствие ключа — 401 AUTHENTICATION_ERROR.
Авторизация: заголовок Authorization: Bearer <ключ> — API-ключ, выданный в личном кабинете (isk_live_<prefix>_<secret>).
Пример вызова
curl -X GET "https://api.iskragen.ru/v1/webhook-endpoints/" \
-H "Authorization: Bearer $ISKRAGEN_API_KEY"
Структура ответа 200
Поля и типы из схемы ответа, это не пример: значения зависят от запроса. Корень — object[].
| Поле | Тип | Обязательное | Описание и ограничения |
|---|---|---|---|
[].active | boolean | да | — |
[].createdAt | string | да | — |
[].eventTypes | string[] | да | — |
[].failureCount | number | да | — |
[].id | string | да | — |
[].lastDeliveryAt | string | null | да | — |
[].url | string | да | — |
Коды ошибок
401 AUTHENTICATION_ERROR— ключ отсутствует, невалиден или отозван.429 RATE_LIMIT_ERROR— превышен лимит запросов либо число одновременных генераций (по умолчанию 5).
POST /v1/webhook-endpoints/
Создать webhook-endpoint. Создаёт endpoint: повтор с тем же URL создаёт второй endpoint, Idempotency-Key не принимается, секрет whsec_… показывается только в этом ответе и повторно получить его нельзя, а rotate-secret выпускает новый секрет, после чего прежний перестаёт действовать; допускается до 5 endpoint на аккаунт, URL должен быть http или https, а localhost и приватные адреса запрещены. События — generation.completed и generation.failed, пустой eventTypes означает все, поддерживается wildcard generation.*; доставка подписана заголовками webhook-id, webhook-timestamp, webhook-signature со значением v1,<base64 HMAC-SHA256> от id.timestamp.body, предусмотрено до 15 доставок с растущими паузами от 5 секунд до 2 суток, после последней, пятнадцатой доставки пауз нет, а ответ 410 сразу отключает endpoint. Требуется API-ключ; действует общий лимит 60 запросов в минуту, превышение возвращает 429 RATE_LIMIT_ERROR с retryAfter, а отсутствие ключа — 401 AUTHENTICATION_ERROR.
Авторизация: заголовок Authorization: Bearer <ключ> — API-ключ, выданный в личном кабинете (isk_live_<prefix>_<secret>).
Тело запроса (application/json)
| Поле | Тип | Обязательное | Описание и ограничения |
|---|---|---|---|
eventTypes | string[] | нет | Допустимые события: generation.completed, generation.failed, generation.*, *. Пустой массив или отсутствие поля подписывает на все события.; элементов ≤ 20 |
url | string | да | формат uri |
Пример вызова
curl -X POST "https://api.iskragen.ru/v1/webhook-endpoints/" \
-H "Authorization: Bearer $ISKRAGEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url":"<url>"}'
Структура ответа 201
Поля и типы из схемы ответа, это не пример: значения зависят от запроса. Корень — object.
| Поле | Тип | Обязательное | Описание и ограничения |
|---|---|---|---|
eventTypes | string[] | да | — |
id | string | да | — |
secret | string | да | — |
url | string | да | — |
Коды ошибок
401 AUTHENTICATION_ERROR— ключ отсутствует, невалиден или отозван.429 RATE_LIMIT_ERROR— превышен лимит запросов либо число одновременных генераций (по умолчанию 5).
DELETE /v1/webhook-endpoints/{id}
Удалить webhook-endpoint. Удаляет свой endpoint и возвращает 204 без тела; повторное удаление возвращает 404. Требуется API-ключ; действует общий лимит 60 запросов в минуту, превышение возвращает 429 RATE_LIMIT_ERROR с retryAfter, а отсутствие ключа — 401 AUTHENTICATION_ERROR.
Авторизация: заголовок Authorization: Bearer <ключ> — API-ключ, выданный в личном кабинете (isk_live_<prefix>_<secret>).
Параметры
| Параметр | Где | Тип | Обязательный | Описание и ограничения |
|---|---|---|---|---|
id | path | string | да | формат uuid |
Пример вызова
curl -X DELETE "https://api.iskragen.ru/v1/webhook-endpoints/<id>" \
-H "Authorization: Bearer $ISKRAGEN_API_KEY"
Структура ответа 204
Схема не описывает JSON-тело ответа; что приходит в ответе — в описании метода выше.
Коды ошибок
401 AUTHENTICATION_ERROR— ключ отсутствует, невалиден или отозван.404— Ресурс не существует или принадлежит другому пользователю429 RATE_LIMIT_ERROR— превышен лимит запросов либо число одновременных генераций (по умолчанию 5).
POST /v1/webhook-endpoints/{id}/rotate-secret
Перевыпустить секрет. Возвращает новый секрет endpoint; старый перестаёт действовать немедленно, без переходного периода. Требуется API-ключ; действует общий лимит 60 запросов в минуту, превышение возвращает 429 RATE_LIMIT_ERROR с retryAfter, а отсутствие ключа — 401 AUTHENTICATION_ERROR.
Авторизация: заголовок Authorization: Bearer <ключ> — API-ключ, выданный в личном кабинете (isk_live_<prefix>_<secret>).
Параметры
| Параметр | Где | Тип | Обязательный | Описание и ограничения |
|---|---|---|---|---|
id | path | string | да | формат uuid |
Пример вызова
curl -X POST "https://api.iskragen.ru/v1/webhook-endpoints/<id>/rotate-secret" \
-H "Authorization: Bearer $ISKRAGEN_API_KEY"
Структура ответа 200
Поля и типы из схемы ответа, это не пример: значения зависят от запроса. Корень — object.
| Поле | Тип | Обязательное | Описание и ограничения |
|---|---|---|---|
secret | string | да | — |
Коды ошибок
401 AUTHENTICATION_ERROR— ключ отсутствует, невалиден или отозван.429 RATE_LIMIT_ERROR— превышен лимит запросов либо число одновременных генераций (по умолчанию 5).