# Callback (вебхуки)

Подписка на события платформы: настройка callback-URL, типы событий, отладка доставки.

## Что такое callback

**Callback** — URL вашей системы, на который платформа отправляет уведомления о событиях: изменение статуса проекта/документа, готовность экспорта, завершение задач. Так вы не опрашиваете API, а реагируете на события.

## Настройка

| Метод | Назначение |
| --- | --- |
| `POST /api/integration/v1/callback` | Создать/обновить настройки уведомлений |
| `GET /api/integration/v1/callback` | Посмотреть текущие настройки |
| `DELETE /api/integration/v1/callback` | Удалить настройки |
| `GET /api/integration/v1/callback/lastErrors` | Последние ошибки доставки |

В настройках указывается URL обработчика и набор событий. Обработчик должен отвечать 2xx быстро; при ошибках доставки платформа накапливает их в `lastErrors`.

## Рекомендации обработчику

1. **Идемпотентность** — событие может прийти повторно; различайте по ID события/объекта.
2. **Быстрый ответ** — возвращайте 200 сразу, тяжёлую обработку делайте асинхронно (очередь).
3. **Логирование** — сохраняйте тела событий для отладки.
4. **Валидация** — проверяйте подпись/источник, если используется.

## Типовой сценарий

«Экспорт готов» → ваш обработчик скачивает файл (`GET /api/integration/v1/document/export/{taskId}`) и кладёт в ваше хранилище.

Список поддерживаемых событий — в Swagger-модели настроек callback ([app.plaia.ru/api/methods](https://app.plaia.ru/api/methods/)).