# 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}.

```bash
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://mcp-everything.ru/integrations/hh-api/scenarios/nayti-vakansii-po-zaprosu.md)
- [Опубликовать вакансию от имени работодателя](https://mcp-everything.ru/integrations/hh-api/scenarios/opublikovat-vakansiyu-ot-imeni.md)
- [Разобрать отклики на вакансию](https://mcp-everything.ru/integrations/hh-api/scenarios/razobrat-otkliki-na-vakansiyu.md)
- [Переписываться с кандидатом в чате](https://mcp-everything.ru/integrations/hh-api/scenarios/perepisyvatsya-s-kandidatom-v-chate.md)

---

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