# Уведомления (webhooks)

Сервер сам сообщит, когда глава озвучена или файл собран.

Вместо того чтобы спрашивать задачу по кругу, укажите у ключа **адрес для уведомлений**: Аккаунт → API → ключ → Изменить.
Адрес — только `https://` и не во внутреннюю сеть. Уведомления приходят о задачах, запущенных этим ключом.

## События

| Событие | Когда | Что в `data` |
|---|---|---|
| `chapter.voiced` | Глава озвучена и собрана | `job`, `book_id`, `chapter_id` |
| `export.ready` | Файл M4B или ZIP собран | `job`, `book_id`, `file_url` (живёт час) |
| `job.failed` | Озвучка или сборка остановилась с ошибкой | `job` (текст в `job.error`) |

## Запрос к вам

`POST` на ваш адрес, тело — JSON. Заголовки:

| Заголовок | Что это |
|---|---|
| `Golosar-Event` | Событие, например `chapter.voiced` |
| `Golosar-Signature` | `t=<время unix>,v1=<подпись>` — см. [Проверка подписи](/developers/signature) |

Ответьте кодом 2xx за 10 секунд. Не ответили — повторим через минуту и через 5 минут, потом перестанем.
События могут прийти не по порядку и, редко, дважды — проверяйте `job.id`.

```json Тело уведомления
{
  "type": "chapter.voiced",
  "data": {
    "job": {
      "id": "01a134d0-e101-75f3-822a-7e5c7ba0f3f3",
      "type": "render",
      "status": "done",
      "credits_used": 15488.0,
      "…": "…"
    },
    "book_id": "01a134d0-dd73-77be-aa8d-0944ffb2b5e3",
    "chapter_id": "01a134d0-ddb7-72aa-b96c-967b596362fe"
  },
  "created_at": "2026-10-13T10:15:02+00:00"
}
```

```http Заголовки
POST /golosar/webhook HTTP/1.1
content-type: application/json
Golosar-Event: chapter.voiced
Golosar-Signature: t=1760350502,v1=5f3a9c…
```