# Webhooks

Уведомления о завершении задач

Базовый адрес — `https://api.iskragen.ru`. Общие правила — в [обзоре справочника](/docs/api-reference).

## 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>`).

### Пример вызова

```bash
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 |

### Пример вызова

```bash
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 |

### Пример вызова

```bash
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 |

### Пример вызова

```bash
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).