Хуки расширения

Расширение конвейеров Charo внешними API — точки подключения, контракт каждой точки, регистрация хука и обработка ошибок.

Что такое хуки

Хуки позволяют подключить ваши внешние API как колбэки в предопределённых точках конвейеров Charo: обработка запросов пользователей, приём документов перед индексацией и отправка документов после индексации. Управление — на странице Админка → Хуки-расширения; хуки также должны быть включены в конфигурации установки.

На каждую точку подключается один хук.

Как это работает

Charo отправляет HTTP POST с JSON-телом на указанный вами URL:

если задан API-ключ, он передаётся в заголовке Authorization: Bearer <ключ>;
успешным считается ответ со статусом 2xx и валидным JSON по схеме точки;
повторных попыток нет — при сбое применяется выбранная стратегия;
успешные вызовы не журналируются, ошибки видны в журнале хука.

Регистрация хука

На странице «Хуки-расширения» нажмите «Подключить» у нужной точки.

Заполните форму «Настройка хука»:

Поле	Что указать
Отображаемое имя	как хук будет виден в списке
URL внешнего API	адрес вашего эндпоинта (должен быть доступен с сервера Charo)
API-ключ	необязательно; передаётся как Bearer-токен
Тайм-аут	максимум ожидания ответа: больше 0 и не более 600 секунд
Стратегия при сбое	«Записать ошибку и продолжить» (soft) или «Останавливать конвейер при сбое» (hard)

После сохранения Charo проверит соединение — статус хука станет «Подключено» либо «Соединение потеряно».

Журнал «Недавние ошибки» на карточке хука показывает ошибки за последние 30 дней; их можно скопировать или скачать файлом.

Точка «Обработка запросов»

Выполняется для каждого запроса пользователя до конвейера — это самая ранняя точка: запрос ещё не сохранён и не обработан. Позволяет переписывать, фильтровать или отклонять запросы: контентная фильтрация, нормализация, удаление персональных данных, аудит.

Тело запроса (payload):

Поле	Тип	Описание
`query`	string	запрос ровно в том виде, как его ввёл пользователь
`user_email`	string \| null	почта пользователя; null для неаутентифицированных
`chat_session_id`	string	UUID чата

Ожидаемый ответ:

Поле	Тип	Описание
`query`	string \| null	запрос для дальнейшей обработки; null или пустая строка — отклонить запрос
`rejection_message`	string \| null	сообщение пользователю при отклонении (иначе — стандартное)

Тайм-аут по умолчанию — 5 секунд: пользователь ждёт ответа. Стратегия по умолчанию — hard: при сбое хука запрос блокируется с сообщением об ошибке.

Точка «Приём документов»

Выполняется для каждого документа перед конвейером индексации — до чанкования и записи. Позволяет фильтровать документы, редактировать содержимое (например, вычищать персональные данные) или отбрасывать документы целиком.

Тело запроса (payload):

Поле	Тип	Описание
`document_id`	string	идентификатор документа (только чтение)
`title`	string \| null	заголовок
`semantic_identifier`	string	человекочитаемое имя (имя файла, заголовок страницы)
`source`	string	тип источника: `confluence`, `google_drive` и т.д. (только чтение)
`sections`	array	секции документа: текстовые (`text`) и изображения (`image_file_id`); у секции может быть `link`
`metadata`	object	метаданные; значения — массивы строк
`doc_updated_at`	string \| null	время изменения в источнике, ISO 8601 UTC
`primary_owners`, `secondary_owners`	array \| null	владельцы: `display_name`, `email`

Ожидаемый ответ:

Поле	Тип	Описание
`sections`	array \| null	секции для индексации в нужном порядке — можно менять, переставлять и удалять; null или пустой список — документ не индексируется
`rejection_reason`	string \| null	причина отклонения для журнала

Содержимое изображений в хук не передаётся: секцию-изображение можно удалить или переставить, но не прочитать.

Тайм-аут по умолчанию — 30 секунд. Стратегия по умолчанию — hard: при сбое хука документ не индексируется.

Точка «Отправка документов»

Срабатывает после успешной индексации каждого документа. Работает по принципу fire-and-forget: тело ответа игнорируется, любой ответ 2xx — успех. Подходит для выгрузки проиндексированных документов во внешние системы: хранилище аналитики, журнал аудита, внутреннюю вики.

Вызывается только для публичных коннекторов (без синхронизации прав и групповых ограничений) — чтобы закрытые документы не уходили во внешнюю систему.

Тело запроса (payload):

Поле	Тип	Описание
`document_id`	string	идентификатор документа
`title`	string \| null	заголовок
`content`	string	полный текст документа (все текстовые секции)
`source`	string	тип источника
`url`	string \| null	ссылка на документ в источнике
`doc_updated_at`	string \| null	время изменения в источнике, ISO 8601 UTC
`metadata`	object	метаданные; значения — массивы строк

Тайм-аут по умолчанию — 30 секунд. Стратегия по умолчанию — soft: ошибки записываются в журнал, индексация продолжается. При стратегии hard сбой хука останавливает текущий батч индексации.

Обработка ошибок

«Записать ошибку и продолжить» (soft) — сбой хука не останавливает конвейер: ошибка попадает в журнал, обработка идёт дальше.
«Останавливать конвейер при сбое» (hard) — сбой останавливает операцию: запрос блокируется / документ не индексируется / батч индексации падает.
Статус «Соединение потеряно» выставляется при сетевых ошибках и ответах 401/403 — проверьте доступность эндпоинта с сервера Charo и API-ключ.
Тайм-аут — тоже сбой: следите, чтобы эндпоинт отвечал быстрее лимита, особенно у точки «Обработка запросов», где ждёт живой пользователь.