Вебхуки та API

API-токени

У розділі Інтеграції → API (потрібен дозвіл Керування API) натисніть Згенерувати новий токен, дайте йому назву й виберіть області дії (scopes):

Область дії	Що дозволяє
API аналітики	Читати аналітику навчання
API подій безпеки	Експортувати журнал аудиту безпеки
API відповідності	Читати докази відповідності
API фішингових подій	Читати події фішингових симуляцій
API сигналів ризику	Надсилати зовнішні сигнали ризику
API інтеграцій	Доступ на запис для партнерських інтеграцій, як-от застосунок Freshservice

Токен показується лише один раз. Зберігайте його в безпечному місці. Токен може робити лише те, що дозволяють його області дії. Токени не мають терміну дії, тож натисніть Відкликати для тих, якими ви більше не користуєтеся. На сторінці перелічено доступні кінцеві точки.

Кампанії, створені через API

Кампанії, створені через API інтеграцій, за замовчуванням не надсилають листів. Щоб увімкнути листи, задайте emailConfig (а за потреби також notifyManagers і ccManager) під час створення, клонування чи оновлення кампанії. Коли campaignStart увімкнено, активація кампанії або додавання людей до вже запущеної надсилає їм лист про старт і сповіщення про призначення (у застосунку, а також через підключені вебхуки чи застосунки Slack/Teams) — так само, як у застосунку. Якщо його вимкнено, ці виклики API не зв’язуються з учасниками. Чернетка, яка запускається автоматично в дату початку, сповіщає учасників так само, як у застосунку. Якщо увімкнути campaignStart для вже запущеної кампанії, учасники, які ще не отримали лист про старт, отримають його протягом приблизно 6 годин.

Групи та навчальні шляхи через API

З областю дії API інтеграцій скрипт може розподіляти людей за навчанням, наприклад за результатом оцінювання. Користувачів визначає їхній зовнішній ID.

GET /api/integration/groups повертає ваші групи і те, чи може API змінювати учасників кожної.
POST /api/integration/groups/{id}/members з {"externalUserIds": [...]} додає людей. Автоматичні навчальні шляхи групи призначаються їм одразу. DELETE /api/integration/groups/{id}/members/{externalUserId} вилучає людину; вже призначене навчання зберігається.
GET /api/integration/learning-paths повертає опубліковані навчальні шляхи, а POST /api/integration/learning-paths/{id}/enrollments з {"externalUserIds": [...], "dueDays": 14} зараховує людей напряму (dueDays необов’язковий).

Невідомі зовнішні ID, а також ID вимкнених користувачів, перелічуються у відповіді, а не призводять до помилки. Учні не отримують сповіщень про такі призначення (ні листа, ні сповіщення в застосунку чи чаті); вебхук learning_path.assigned усе одно надсилається. Групи, синхронізовані з вашого постачальника ідентичності, і групи, що надають роль, змінювати через API не можна.

Приклад: розподіл за результатом оцінювання. Створіть групу для кожного діапазону балів (скажімо, ≤45, 46–70 і 71+), задайте кожній власні автоматичні навчальні шляхи, і нехай ваш скрипт додає кожну людину до групи відповідно до її бала.

Вебхуки

У розділі Інтеграції → Вебхуки натисніть Додати вебхук і введіть назву, URL кінцевої точки, Секрет підпису (якщо залишити порожнім, його буде згенеровано) та події, які потрібно надсилати:

Вкладка «Вебхуки»

Група	Події
Кампанії	`campaign.assigned`, `campaign.deadline_approaching` (15 днів), `campaign.deadline_imminent` (5 днів), `campaign.deadline_final_day` (1 день), `campaign.completed`
Навчальні шляхи	`learning_path.assigned`, `learning_path.completed`
Вправи	`exercise.completed`
Бейджі	`badge.awarded`
Фішингові симуляції	`phishing.simulation.failed`, `phishing.reported`
Чат-застосунки	`chat.message.reported` (працівник скористався Report to Security у Slack; містить постійне посилання на повідомлення)
Оцінювання ризиків	`assessment.topic_gap_detected` (тема стала прогалиною в знаннях працівника; містить ключ теми та `source`: `answers` або `deadline` — для теми, на яку працівника запросили, але він не відповів), `assessment.baseline_completed` (працівник завершив базове оцінювання). Для підписки на них, а також для зміни URL, секрету чи активації кінцевої точки, яка їх отримує, потрібен дозвіл Перегляд індивідуального ризику.

Кожен запит — це JSON POST із такими заголовками:

X-Webhook-Id
X-Webhook-Timestamp
X-Webhook-Signature: sha256=<HMAC-SHA256 of the body, using your signing secret> (HMAC-SHA256 тіла запиту, обчислений з вашим секретом підпису)

Перевіряйте підпис, перш ніж довіряти запиту. Невдалі доставки повторюються ще до 5 разів: через 1 хвилину, 5 хвилин, 30 хвилин, 2 години та 12 годин. Для усунення несправностей скористайтеся Тестовий запит і Журнал доставки.