разработчику · статья 30

API-ключи и вебхуки

Эта статья — для разработчика или интегратора: вы хотите обращаться к Worken из своего кода — с сайта, из CRM, из 1С — или получать события платформы на свой сервер. Для обычной работы в кабинете ключи не нужны ни разу: всё, что описано в статьях 01–27, работает без них. Экран живёт в меню Настройки → API и вебхуки — отдельный режим разработчика для него включать не нужно. Видят раздел Владелец и Администратор; выпускает и отзывает ключи только Владелец — Администратор смотрит, но не распоряжается. Внутри три вкладки — «Ключи», «Вебхуки» и «Журнал вызовов», — а единственная лаймовая кнопка экрана,Выпустить ключ, стоит в шапке над вкладками: это главное действие всего раздела.

Вкладка «Ключи»: куда обращаться и чем

Первая вкладка отвечает на два вопроса интеграции: по какому адресу стучаться и каким ключом представляться.

Вкладка «Ключи» экрана «API и вебхуки»: крошка «Настройки / API и вебхуки», лаймовая кнопка «Выпустить ключ» в шапке; блок «Куда обращаться» с тремя строками — базовый адрес https://api.worken.ru/v1, адрес MCP https://mcp.worken.ru/v1/sse, проект prj_01K2FDEMOPROMO2026, у каждой кнопка копирования; ниже таблица из четырёх ключей с колонками имя, ключ, права, создан, последний вызов, состояние — два АКТИВЕН, один ВЫКЛЮЧЕН, один ОТОЗВАН — Вся вкладка «Ключи»: адреса, идентификатор проекта и таблица ключей.

Блок «Куда обращаться» стоит наверху и виден всегда, даже пока ключей нет. В нём три строки, у каждой — кнопка копирования.Базовый адрес — https://api.worken.ru/v1: сюда идут обращения из вашего кода по HTTP. Адрес MCP —https://mcp.worken.ru/v1/sse: он для подключения ИИ-среды, о нём — в шаге 6. Проект —prj_01K2FDEMOPROMO2026: идентификатор проекта, который вы называете при обращении; ключ выпускается на проект, и его права за границы проекта не выходят.

Ниже — таблица ключей: имя, сам ключ маской видаwk_live_9f2c••••••••4a71, права, дата выпуска, последний вызов и состояние. Колонка «последний вызов» — самый быстрый ответ на вопрос «жива ли интеграция»: у работающего ключа там «сегодня в 14:07», у забытого — «ни разу не вызывался». Строка прав — например, «7 семейств, 41 инструмент» — раскрывается щелчком в список семейств.

Выпустить ключ: имя, права, срок жизни

Кнопка Выпустить ключ в шапке открывает форму из трёх частей:

Клик по лаймовой кнопке «Выпустить ключ» в шапке экрана — открывается модалка с полем «Имя ключа», списком «Права по семействам» и сроком жизни; затем имя заполняется «Ключ сайта», семейству virts выдаётся «чтение», счётчик показывает «выбрано: 1 из 12 семейств · 9 из 75 инструментов» — «Выпустить ключ» → форма: имя, права по семействам, срок жизни.

Имя ключа — по-русски и по назначению: «Ключ сайта», «Ключ 1С — выгрузка расписания». Именно имя вы потом увидите в журнале вызовов, поэтому «test2-final» сыграет против вас.Права раздаются не списком из 75 галочек, а по двенадцати семействам инструментов — virts, threads, knowledge, billing и так далее; у каждого семейства три уровня: нет доступа,чтение и чтение и запись. Под списком живёт счётчик — «выбрано: 2 из 12 семейств · 14 из 75 инструментов», — по нему видно, насколько широкий ключ вы собрали. Срок жизни — бессрочно или 30, 90, 365 дней.

Модалка «Выпустить ключ»: имя «Ключ сайта», список «Права по семействам» — virts 9 со значением «чтение», vector_stores 9, knowledge 4, threads 5 со значением «чтение», billing 4, projects 6 «нет доступа»; строка «выбрано: 2 из 12 семейств · 14 из 75 инструментов», срок жизни «Бессрочно», кнопки «Отмена» и лаймовая «Выпустить» — Заполненная форма: чтение для virts и threads, остальным — нет доступа.

Кнопка Выпустить оживает, когда есть имя и хотя бы одно семейство с доступом.

начинайте с «чтения»Ключ, у которого всем нужным семействам выдано только «чтение», покрывает большинство интеграций: выгрузки, отчёты, синхронизацию справочников. «Чтение и запись» добавляйте по одному семейству и только тогда, когда интеграция действительно что-то меняет — так утечка такого ключа стоит заметно дешевле.

Ключ целиком показывается один раз

После «Выпустить» модалка меняется на показ секрета:

Модалка «Ключ выпущен»: имя «Ключ сайта», полное значение wk_live_8f41d2c09b7a4e63a1f5c8d90b2e7614 с кнопкой копирования, оранжевая плашка «ВНИМАНИЕ — Это единственный раз, когда мы показываем ключ целиком. Закроете — восстановить будет нельзя, только выпустить новый», внизу лаймовая кнопка «Ключ сохранён — закрыть» — Единственный показ полного значения. Дальше — только маска в таблице.

Полное значение wk_live_… существует в открытом виде ровно здесь и ровно один раз. Модалку не закрыть ни крестиком, ни щелчком мимо — только кнопкой Ключ сохранён — закрыть: платформа заставляет вас сначала унести ключ в своё хранилище секретов. Закрыли, не сохранив, — значение не восстановить, только выпустить новый ключ.

Дальше ключ живёт в таблице в трёх состояниях.АКТИВЕН — работает. ВЫКЛЮЧЕН — обратимая пауза: меню⋮ → «Выключить», обратно — «Включить»; удобно, чтобы на время работ заглушить интеграцию, не трогая сам ключ. ОТОЗВАН — необратимо: в том же меню «Отозвать…», и для подтверждения нужно ввести имя ключа руками. Кнопки «Удалить» здесь нет вовсе — об этом прямо написано под таблицей: отозванный ключ остаётся в ней навсегда, как след — видно, что ключ был, когда выпущен и когда отозван.

ключ — это доступ к проекту от вашего имени Всё, что разрешено правами ключа, его предъявитель сделает в вашем проекте — и в журнале это будут ваши вызовы. Храните ключ в хранилище секретов, не вписывайте в код и не коммитьте в репозиторий, наружу не показывайте. Утёк — сразу «Отозвать…» и выпустить новый: отзыв срабатывает мгновенно, все обращения старым ключом получают отказ.

Вкладка «Вебхуки»: события наружу

Ключи — это когда ваш код спрашивает Worken. Вебхуки — обратное направление: платформа сама шлёт событие на ваш адрес, как только оно случилось — новый разговор, «требуется ваше решение», проиндексирован файл, отработал сценарий, тает баланс.

Вкладка «Вебхуки»: строка «2 вебхука · работает 1 · ошибка 1» и кнопка «Добавить вебхук»; карточка https://gippokrat.ru/hooks/worken со статусом РАБОТАЕТ, событиями «создан новый разговор», «требуется ваше решение», «файл проиндексирован», строкой «доставок за 7 дней 99, успешных 97 — это 98 %», секретом подписи whsec_••••2d19 и десятью доставками с кодом 200; ниже карточка https://crm.gippokrat.ru/api/worken со статусом ОШИБКА, строкой «доставок за 7 дней 37, успешных 23 — это 62 %, неудачных 14», кнопкой «Повторить 14 неудачных» и доставками с кодом 502, попытка 5 / 5, у каждой кнопка «Доставить снова» — Две карточки: вебхук, который работает, и вебхук, в который платформа не может достучаться.

Добавить вебхук — вторичная кнопка на самой вкладке. В форме два обязательных поля: адрес обработчика — строгоhttps://… — и события, которые слать: десять штук на выбор, у каждого машинное имя видаapproval.requested и русская подпись «требуется ваше решение». Кнопка Проверить шлёт на адрес тестовое событие и ждёт ответ 200 — «Сохранить» открывается после пройденной проверки. Если ваш сервер ещё не поднят, есть тихая ссылка «Сохранить всё равно».

Каждый вебхук — карточка. В шапке адрес и состояние: зелёноеРАБОТАЕТ или красное ОШИБКА. Внутри — события, счёт доставок за 7 дней («доставок 99, успешных 97 — это 98 %») исекрет подписи маской whsec_…: секрет платформа выдаёт при создании вебхука и подписывает им каждое событие — проверяйте подпись в обработчике, чтобы не принять чужую подделку за событие Worken.

Ниже — последние 10 доставок: время, событие, код ответа вашего сервера и номер попытки. На неудачную доставку платформа ходит до пяти раз — «попытка 5 / 5» с кодом 502 значит, что все пять упёрлись в ошибку. У каждой неудачной естьДоставить снова, а в карточке целиком —Повторить 14 неудачных: после починки сервера события доедут заново в исходном порядке. Удаления у вебхуков, как и у ключей, нет — не нужен, так выключите.

Журнал вызовов: где искать ошибку интеграции

Третья вкладка пишет каждое обращение по ключу — и те, что подняли сотрудника, и дешёвые чтения, и отказы:

Вкладка «Журнал вызовов»: фильтры «Ключ: все», «Инструмент: все», «Код: все», «7 дней»; таблица с колонками время, ключ, инструмент, код, длительность, W, адрес источника — строки с кодом 200 зелёным, строка worken_knowledge_search с кодом 429 жёлтым, строка «Старый ключ разработчика» с кодом 401 и подписью «Ключ отозван 1 августа»; строка раскрыта, под ней панели «запрос» {"virt":"bot_7427","message":"ping"} и «ответ» {"error":"key_revoked"} — Журнал с раскрытой строкой отказа: запрос и ответ видны прямо в таблице.

Колонки: время, ключ — всегда именем, значениеwk_live_… в журнале не появляется никогда, журнал можно спокойно копировать и пересылать; инструмент — что вызывали, в том же написании, что и в правах ключа (worken_virts_ask, worken_resources_find);код ответа — зелёный 2xx, жёлтый 4xx, красный 5xx; длительность; W — сколько воркенов стоил вызов: чтение — 0.00, а вызов, поднявший сотрудника, — свои 0.03 или 0.09; и адрес источника — с какого IP пришли.

Ошибка интеграции ищется так: фильтрами наверху сузьте журнал — по ключу, по инструменту, по коду, за сегодня, 7 или 30 дней, — и раскройте подозрительную строку щелчком: под ней покажутсязапрос и ответ как есть. Код 429 с ответомrate_limited — вы стучитесь слишком часто, в ответе лежит retry_after. Код 401 с подписью «Ключ отозван 1 августа» — чей-то код всё ещё ходит отозванным ключом: по имени ключа и адресу источника видно, какую интеграцию забыли перевести на новый.

MCP: сотрудники и данные — из вашей ИИ-среды

Вторая строка блока «Куда обращаться» — адрес MCP:https://mcp.worken.ru/v1/sse. MCP — открытый протокол, по которому ИИ-среды подключают внешние инструменты; если вы работаете в редакторе кода или ассистенте с поддержкой MCP, добавьте этот адрес и ключ — и все 75 инструментов платформы в двенадцати семействах станут доступны прямо оттуда: спросить сотрудника, прочитать диалог, поискать по базе знаний, дописать строку в справочник. Права действуют те же, что выданы ключу, — отдельной настройки для MCP нет: семейства в форме выпуска ключа и есть семейства инструментов MCP.

У этой вкладки есть обратная сторона: здесь платформа отдаёт свои инструменты вашему коду, а в соседнем пункте меню —Настройки → Локальные инструменты — вы отдаёте свои инструменты сотрудникам Worken: расписание из МИС, печать документов, всё, что живёт на вашей стороне. Это отдельная статья — статья 31.

К оглавлению Следующая статья: Локальные инструменты (MCP)