HeadHunter API (hh.ru): Получать уведомления о новых откликах

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

Узнавать о новых откликах и сообщениях сразу, без опроса.

1. Подпишись: POST /webhook/subscriptions с url своего обработчика и actions — списком нужных событий (типы событий — в документации вебхуков). Доступно только работодателю; на приложение — один URL.
2. Колбэк приходит POST-запросом с action_type, id и payload (vacancy_id, resume_id, chat_id и др.). Отвечай 2xx в течение 5 секунд, на повтор с тем же id — 409.
3. Доставка не гарантирована: раз в несколько часов сверяй отклики через GET /negotiations.
4. Список подписок — GET /webhook/subscriptions, удалить — DELETE /webhook/subscriptions/{subscription_id}.

curl -X POST https://api.hh.ru/webhook/subscriptions \
  -H "Authorization: Bearer $HH_TOKEN" -H 'HH-User-Agent: MyApp/1.0 (dev@example.ru)' \
  -H 'Content-Type: application/json' \
  -d '{"url": "https://example.ru/hh/webhook", "actions": [{"type": "<тип события>"}]}'

Базовые URL

• Боевой: https://api.hh.ru
• Запросы ко всем сайтам группы идут на один адрес; нужный сайт задаётся параметром (по умолчанию ), локаль: ?host=

Авторизация

Тип: OAuth 2.0

OAuth 2.0. Токен передаётся в заголовке Authorization: Bearer {ACCESS_TOKEN}.

• Токен пользователя (authorization code): пользователь открывает https://hh.ru/oauth/authorize?response_type=code&client_id={client_id}&state={state}&redirect_uri={redirect_uri}, затем authorization_code из редиректа обменивается на access_token и refresh_token запросом POST https://api.hh.ru/token. Поддерживается PKCE (code_challenge, code_challenge_method=S256).
• Обновление: POST https://api.hh.ru/token с refresh_token; refresh-токен одноразовый и работает только после истечения access_token (срок — expires_in, в секундах).
• Токен приложения (client credentials): срок жизни не ограничен, при повторном запросе прежний отзывается; запрашивать не чаще раза в 5 минут. Актуальный токен виден владельцу на https://dev.hh.ru/admin.

Параметры /oauth/authorize: skip_choose_account=true — не показывать выбор аккаунта, force_login=true — всегда показывать форму входа, role (applicant или employer) с force_role=true — требовать нужную роль.

В каждом запросе обязателен заголовок User-Agent или HH-User-Agent (при обоих учитывается HH-User-Agent); без него — 400 Bad Request.

User-Agent: MyApp/1.0 (my-app-feedback@example.com)

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

GET /negotiations — Список откликов и приглашений

По умолчанию сортировка по дате обновления, от новых к старым. Активные отклики — ?status=active.

Параметр	Где	Тип	Обяз.	Описание
vacancy_id	query	string	да	ID вакансии (обязателен для работодателя)
status	query	string	нет	Статус из applicant_negotiation_status
order_by	query	string	нет	Сортировка из negotiations_order
order	query	string	нет	asc или desc
has_updates	query	boolean	нет	Только с непросмотренными сообщениями
with_job_search_status	query	boolean	нет	Вернуть статус поиска работы кандидата
with_generated_collections	query	boolean	нет	Вернуть сгенерированные коллекции
page	query	number	нет	Номер страницы
per_page	query	number	нет	По умолчанию 20

POST /webhook/subscriptions — Подписка на уведомления

Успех — 201, в ответе id подписки. Только для работодателя.

Пример колбэка:

Параметр	Где	Тип	Обяз.	Описание
actions	body	array	да	Список событий
url	body	string	да	URL для POST-уведомлений

Пример запроса:

{
"action_type": "string",
"id": "string",
"payload": {
"chat_id": "string",
"employer_id": "string",
"negotiation_date": "string",
"resume_id": "string",
"topic_id": "string",
"vacancy_id": "string"
},
"subscription_id": "string",
"user_id": "string"
}

GET /webhook/subscriptions — Список подписок

Параметр	Где	Тип	Обяз.	Описание
HH-User-Agent	header	string	да	Название приложения и почта разработчика

DELETE /webhook/subscriptions/{subscription_id} — Удаление подписки

Параметр	Где	Тип	Обяз.	Описание
subscription_id	path	string	да	Идентификатор подписки

Нюансы

• Пагинация: page=N&per_page=M, нумерация с нуля; ответ — found, per_page, pages, page, items.
• Неизвестные и недокументированные параметры игнорируются; недокументированные поля в ответах не рекомендуется использовать.
• Длинные ответы сжимаются gzip.
• Поддерживается CORS; для отладки есть /cors (HEAD, GET, POST, PUT, DELETE), для JSONP — ?callback=callback_name.
• Вебхуки: на одно приложение — один URL. Ваш сервер отвечает 2xx или 409 для дубликата (определяется по id). Без ответа за 5 секунд колбэк отправляется повторно; доставка не гарантирована. При долгих сбоях подписка блокируется, при отзыве доступа удаляется.
• Методы /negotiations/{nid}/messages устарели — переписка ведётся через /common/chats.
• Просмотр резюме с контактами списывает контакт один раз на компанию; если контакты скрыты соискателем, просмотр всё равно спишется — проверяйте hidden_fields.

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

• Найти вакансии по запросу
• Опубликовать вакансию от имени работодателя
• Разобрать отклики на вакансию
• Переписываться с кандидатом в чате

---

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