Хантфлоу API v2: Получать события через вебхук

Сценарий из mcp-everything. Актуально на 2026-10-24.

Реагировать на смену этапа кандидата или новую вакансию сразу: уведомить менеджера, завести сотрудника в HR-системе.

Создай вебхук: POST /accounts/{account_id}/hooks с url, secret, active = true и webhook_events — нужными событиями (APPLICANT, VACANCY, RESPONSE, OFFER и др.).
Хантфлоу присылает события POST-запросом на url. Используй secret, чтобы отличать настоящие запросы, — способ проверки описан в документации вебхуков.
По ID из события получай актуальные данные: например, GET /accounts/{account_id}/applicants с vacancy_id.

curl -X POST https://api.huntflow.ru/v2/accounts/<account_id>/hooks \
  -H "Authorization: Bearer $HF_TOKEN" -H 'Content-Type: application/json' \
  -d '{"url": "https://example.ru/huntflow/webhook", "secret": "s3cr3t_Random_42", "active": true, "webhook_events": ["APPLICANT", "VACANCY"]}'

Базовые URL

Боевой: https://api.huntflow.ru/v2
Тестовый (песочница): https://sandbox.huntflow.dev
Официальный Python-клиент Хантфлоу по умолчанию указывает хост .: https://api.huntflow.ai

Авторизация

Тип: Bearer-токен

Токен создаётся в настройках Хантфлоу: «Настройки» → «API» → «Добавить токен»; выдаётся пара access_token и refresh_token. Все запросы передают заголовок Authorization: Bearer <access_token>.

access_token действует 7 дней, refresh_token — 14 дней; если refresh-токен не использовать 14 дней, пару нужно создать заново.
Истёкший токен даёт 401 с type: authorization_error и detail: token_expired — тогда вызывайте POST /token/refresh.

Методы сценария

GET /accounts/{account_id}/applicants — Список кандидатов

Параметр	Где	Тип	Обяз.	Описание
`account_id`	path	integer	да	ID организации
`count`	query	integer	нет	Элементов на странице, по умолчанию 30
`page`	query	integer	нет	Номер страницы, по умолчанию 1
`status`	query	integer	нет	ID этапа подбора
`vacancy_id`	query	integer	нет	ID вакансии
`agreement_state`	query	string	нет	Статус согласия на обработку ПДн; нельзя вместе со status

POST /accounts/{account_id}/hooks — Создание вебхука

Параметр	Где	Тип	Обяз.	Описание
`account_id`	path	integer	да	ID организации
`url`	body	string	да	URL вебхука
`secret`	body	string	да	Секретный ключ
`active`	body	boolean	да	Активен ли вебхук
`webhook_events`	body	array	да	APPLICANT, VACANCY, RESPONSE, OFFER, VACANCY-REQUEST, RECRUITMENT-EVALUATION, SURVEY-QUESTIONARY
`type`	body	string	нет	USER (по умолчанию) или APPLICATION

Нюансы

Почти все методы работают в контексте организации: account_id берётся из GET /accounts.
ID этапов подбора — из GET /accounts/{account_id}/vacancies/statuses, причины отказа — из /rejection_reasons, источники резюме — из /applicants/sources.
Для массовой выборки кандидатов удобнее курсорный поиск search_by_cursor.
Есть также методы заявок на вакансии, мультивакансий, меток, справочников, регионов, подразделений, офферов, анкет, журнала действий (action_logs) и производственного календаря.

Другие сценарии

Если этого недостаточно — официальная документация: https://api.huntflow.ru/v2/docs Вся интеграция одним документом: https://mcp-everything.ru/integrations/huntflow.md