Приём данных и исходящие вебхуки

Приватный external-источник принимает текст вашей системы, а исходящие вебхуки сообщают об изменениях состояния. Загрузки собственного исполняемого кода здесь нет. REST использует API-ключ workspace; MCP — отдельное OAuth-подключение. Все запросы.

Передать текстовые материалы

Создайте источник через POST /v1/external-sources, затем отправляйте материалы в /v1/external-sources/{id}/items. Для настройки используйте ключ владельца, а для передающей системы — отдельный ingest-ключ, ограниченный этим источником.

Тело ingest_materials

{
  "items": [{
    "externalId": "article-42",
    "version": "1",
    "title": "Заметки о выпуске",
    "text": "Выпуск доступен.",
    "publishedAt": "2026-10-20T12:00:00Z",
    "url": "https://example.com/releases/42",
    "metadata": {"category": "release"}
  }]
}

Обязательны externalId, version, title, text, publishedAt; время — ISO 8601 с часовым поясом. URL и JSON-метаданные необязательны. Ограничения: 50 элементов в пакете, 65 536 символов текста на элемент, 1 000 символов заголовка, 16 КиБ метаданных, 1 МиБ тела запроса. Изображения передаются отдельной загрузкой ассетов, а не бинарными данными в text.

Принятый HTTP-запрос может содержать отклонённые элементы. Проверяйте каждый items[index]: у accepted есть id сырого материала и jobId; duplicate ссылается на сохранённую версию; rejected содержит код. jobId в квитанции может появиться раньше строки workspace-задания, пока отправляется durable outbox. В этот промежуток проверяйте также результаты и состояние источника.

Дедупликация: workspace + источник + внешний ID + версия. Повтор сохранённой версии не запускает новую обработку и списание за приём. Изменённое содержимое с прежней версией конфликтует; для настоящего обновления передайте новую версию. После таймаута повторяйте исходный запрос с прежним ключом, а не создавайте новую версию из-за сетевой ошибки.

Подписаться на результат

Тело create_webhook

{
  "name": "Получатель результатов",
  "url": "https://receiver.example.com/signailist",
  "events": ["processing.completed", "digest.ready", "publication.sent"],
  "includeResult": true
}

В примере адрес-заглушка: замените его публичным HTTPS endpoint своей системы. Сразу сохраните полученный секрет подписи в хранилище секретов — он показывается один раз. Идемпотентный повтор ответа сохраняет ID подписки, но не возвращает секрет. Если первый ответ потерян, выполните ротацию.

Событие	Значение
processing.completed	Предварительная обработка сохранена; готовность последующего AI проверяется отдельно
processing.failed	Ошибка workspace-задания обработки/AI; проверьте задание
digest.ready	Дайджест перешёл в состояние готовности/проверки; это не квитанция публикации
approval.required	Кандидат публикации ожидает утверждения
publication.sent	Доставка публикации перешла в sent
publication.failed	Ошибка доставки публикации
publication.unknown	Результат провайдера не подтверждён; автоматически не отправляйте заново
source.failed	Источник перешёл в состояние ошибки
balance.low	Баланс пересёк USD 1 вниз
balance.depleted	Баланс пересёк ноль вниз
limit.reached	Лимит workspace или подключения остановил платный этап

Конверт содержит schemaVersion, id, type, createdAt, workspaceId, objectId, data. При includeResult: false данные краткие — ссылка/состояние объекта; при true — снимок результата на момент перехода. Несколько событий одного объекта могут обозначать разные переходы. Для текущего состояния прочитайте объект через REST/MCP, а не полагайтесь на старый снимок.

Проверить, сохранить и подтвердить

Заголовки: Signailist-Event-Id, Signailist-Timestamp (Unix seconds), Signailist-Signature. HMAC-SHA256 вычисляется по UTF-8 timestamp, точке и точным исходным байтам тела. Подпись — hex с префиксом v1=. Сравнивайте за постоянное время и отклоняйте timestamp дальше пяти минут от ваших часов; синхронизируйте часы сервера. После проверки подписи сверьте ID заголовка и конверта.

Скачать Python-проверку подписи. Не проверяйте подпись по заново сериализованному JSON: пробелы и порядок ключей могут измениться. При ротации старый и новый секреты действуют совместно 24 часа; заголовок может содержать несколько подписей через запятую. В период перехода принимайте корректную подпись от любого из доверенных секретов.

Надёжно сохраните проверенное событие и ID дедупликации, затем быстро верните любой 2xx. Тяжёлую работу поставьте в свою очередь. Если сохранить событие нельзя, верните ошибку для повторной доставки. Гарантия — минимум один раз, возможны дубликаты и другой порядок. Не выполняйте незащищённый внешний эффект до сохранения дедупликации.

Повторы, биллинг и восстановление

До восьми попыток в течение суток с увеличением интервала, затем ошибка доставки. list_webhook_deliveries / GET /v1/webhooks/deliveries показывают состояние, число попыток и последний HTTP-результат. retry_webhook перезапускает неуспешное платное уведомление; { "ok": true } подтверждает запрос, но не успешный приём получателем. При повторах ID события сохраняется. История хранится 30 дней.

Физические попытки расходуют общий баланс, включая ошибки HTTP. Повтор клиентского запроса сам по себе повторного списания не создаёт. Уведомления об исчерпании баланса/лимите имеют ограниченную бесплатную доставку — максимум три попытки на событие; её нельзя перезапускать как платную доставку. Подробнее в биллинге.

Принимаются только публичные HTTPS-адреса. Credentials в URL, внутренние адреса и небезопасные DNS-ответы запрещены. Перенаправления не выполняются: при смене адреса обновите конфигурацию. Пауза подписки останавливает доставку, но сохраняет историю.

Повтор исходящего вебхука не равен повторной публикации: событие publication.unknown требует проверки назначения, а не новой отправки публикации.