Подключение и приём событий

Webhook сообщает вашей системе об изменениях в HRlink без постоянного опроса API. Когда происходит нужное событие, HRlink отправляет на ваш адрес HTTP-запрос. В одном запросе может быть несколько событий.

Событие содержит данные, которые нужны для реакции на изменение. Если вашей системе нужны другие поля или актуальное состояние документа, запросите их через публичный REST API.

Для on-premise поставок

Webhook доступен после установки приложения HRlink релиза 103.

Как работает webhook

1. В HRlink происходит событие, например документ отправляют на подписание.
2. HRlink отправляет на ваш обработчик POST с JSON-массивом событий.
3. Обработчик проверяет токен и записывает весь массив.
4. Обработчик возвращает 200 OK. После этого HRlink считает весь массив доставленным.
5. Ваша система обрабатывает записанные события.

Такая последовательность отделяет приём данных от бизнес-обработки. Даже если обработка займёт время или завершится ошибкой, принятые события останутся в вашем хранилище или очереди.

Что подготовить

Что подготовить	Для чего это нужно
Публичный HTTPS-адрес	HRlink отправляет на него события через интернет
TLS-сертификат доверенного центра сертификации	HRlink должен установить защищённое соединение с обработчиком
Имя HTTP-заголовка и токен	Обработчик проверяет по ним отправителя запроса
Долговременное хранилище или очередь	События не потеряются после перезапуска обработчика
Контакт специалиста	Специалист проверит подключение со стороны вашей системы

Долговременное хранилище сохраняет данные после перезапуска приложения. Это может быть база данных или очередь с подтверждением записи.

Как подать заявку

Отправьте заявку в Службу заботы. Укажите:

• адрес тенантаTenantЭкземпляр системы HRlink на отдельном домене (например, company.hr-link.ru). Внутри одного тенанта может быть несколько пространств клиентов. HRlink;
• публичный HTTPS-адрес обработчика;
• нужные типы событий или запрос на все доступные типы;
• имя HTTP-заголовка для токена;
• контакт специалиста, который проверит подключение.

Команда HRlink настроит подписку по заявке.

Подписка получает события всего тенантаTenantЭкземпляр системы HRlink на отдельном домене (например, company.hr-link.ru). Внутри одного тенанта может быть несколько пространств клиентов.. HRlink может отобрать события только по eventType. Если в тенантеTenantЭкземпляр системы HRlink на отдельном домене (например, company.hr-link.ru). Внутри одного тенанта может быть несколько пространств клиентов. несколько клиентов, используйте clientId, когда это поле есть в событии. Поле отсутствует, если событие не связано с клиентом.

Для одного тенантаTenantЭкземпляр системы HRlink на отдельном домене (например, company.hr-link.ru). Внутри одного тенанта может быть несколько пространств клиентов. можно настроить любое количество подписок.

Как безопасно передать токен

Создайте токен на своей стороне. Не указывайте его значение в тексте заявки, письме или сообщении чата.

Передайте значение токена удобным для вас защищённым способом. Например:

• через корпоративное хранилище или сервис передачи секретов;
• в зашифрованном файле, передав пароль по другому каналу.

Если подходящего способа нет, согласуйте его со Службой заботы. Имя HTTP-заголовка не содержит секретных данных, поэтому его можно указать в заявке.

Требования к обработчику

Обработчик должен:

• быть доступен из интернета;
• использовать HTTPS;
• предъявлять сертификат доверенного центра сертификации;
• принимать POST с Content-Type: application/json;
• проверять токен в согласованном HTTP-заголовке;
• принимать JSON-массив, даже если в нём только одно событие;
• возвращать 200 OK, когда весь массив записан.

Самоподписанный сертификат не подходит. Такой сертификат нельзя проверить через общедоступную цепочку доверия, поэтому HRlink не устанавливает с ним соединение.

Не записывайте токен в журналы приложения. Иначе сотрудник с доступом к журналам сможет использовать его для отправки поддельного запроса.

Как выглядит запрос

В этом примере имя заголовка X-HRlink-Webhook-Token условное. В заявке можно выбрать другое имя.

POST /hrlink/webhooks HTTP/1.1
Host: integration.example.com
Content-Type: application/json
X-HRlink-Webhook-Token: {webhook-token}

[
  {
    "id": "c4c74325-7e4a-4f9b-b270-33415f087fb2",
    "clientId": "f73fd3ee-89f6-45a2-a90d-fc48f615c4ef",
    "eventDate": "2026-07-16T09:41:30Z",
    "eventType": "DOCUMENT_PRINT_FORM_UPDATED",
    "payload": {
      "document": {
        "id": "6ba5818b-6df0-451a-b45f-040359d6fdad",
        "externalId": "DOC-2026-0042",
        "baseDocument": null,
        "version": 2,
        "printFormUpdatedDate": "2026-07-16T09:41:30Z"
      },
      "printFormLastDocflowParticipant": null
    },
    "correlationId": "6ba5818b-6df0-451a-b45f-040359d6fdad"
  }
]

Точные поля и значения для каждого типа описаны на странице События и поля.

Как принять массив событий

1. Сравните токен из HTTP-заголовка со значением, которое хранится в вашей системе. Если токен не совпадает, отклоните запрос.
2. Разберите JSON-массив и проверьте обязательные поля каждого события.
3. Запишите весь массив в долговременное хранилище или очередь и дождитесь подтверждения записи.
4. Используйте id события как уникальный ключ. Если событие с таким id уже записано, не создавайте вторую запись.
5. Верните 200 OK.
6. Запустите бизнес-обработку записанных событий.

Не возвращайте 200 OK, если не удалось записать хотя бы одно событие из массива. HRlink подтверждает или повторяет весь массив целиком.

Не отклоняйте запрос из-за неизвестного необязательного поля. В будущем в событии могут появиться дополнительные поля, которые не мешают обработке уже известных данных.

Как HRlink подтверждает доставку

Результат запроса	Как его учитывает HRlink
200 OK	Весь массив доставлен
Любой другой HTTP-статус	Массив не доставлен
Таймаут, ошибка DNS или TLS	Массив не доставлен

Только точный статус 200 OK подтверждает доставку. Статусы 201, 202, 204 и другие ответы 2xx не подтверждают её.

До ответа 200 OK запишите весь массив и получите подтверждение записи. Если ответить раньше, а затем потерять данные из памяти процесса, HRlink уже будет считать массив доставленным и не отправит его повторно из-за этой ошибки.

Что происходит при ошибке

После неуспешной доставки HRlink планирует повторные попытки:

Попытка	Задержка после предыдущей ошибки
1	1 минута
2	2 минуты
3	4 минуты
4	8 минут
5	16 минут
6	32 минуты

Фактическая отправка может произойти позже указанного времени. Эти интервалы не являются гарантированным сроком доставки.

Если очередная попытка завершается ошибкой после окончания часового периода повторов, HRlink деактивирует подписку. Чтобы возобновить доставку, обратитесь в Службу заботы.

Один HTTP-запрос содержит непустой массив. Действующий максимальный размер массива — 1000 событий.

Размер массива, интервалы повторов и часовой период — действующие параметры доставки, а не гарантированные сроки или неизменные ограничения. HRlink может изменить их без отдельного уведомления и отразит новые значения в документации.

Дубликаты и порядок событий

Одно событие может прийти повторно. Например, обработчик мог записать массив, но соединение прервалось до того, как HRlink получил 200 OK. Используйте id события как уникальный ключ и не выполняйте бизнес-действие второй раз для уже обработанного id.

Не полагайтесь на порядок прихода событий. Поле eventDate показывает время события, а correlationId связывает его с документом или задачей. Если порядок важен для вашего процесса, получите актуальное состояние объекта через REST API.

Сверка через REST API

Запрашивайте объект после события, если вашей системе нужны поля, которых нет в payload:

• Получить документ;
• Получить документ по externalId;
• Получить реестр документов.

После длительного сбоя периодически сверяйте реестр по statusLastModifiedDateFrom. Алгоритм описан в разделе Incremental polling.

Как проверить подключение

До подключения отправьте на обработчик тестовый POST по примеру из этой страницы. Проверьте, что обработчик:

1. принимает запрос только с правильным токеном;
2. сохраняет весь JSON-массив;
3. не создаёт вторую запись при повторе события с тем же id;
4. возвращает точный статус 200 OK после записи;
5. не записывает токен в журнал.

После подключения проверьте вместе с указанным в заявке специалистом, что первое событие появилось в вашей системе.

Если события не приходят

Проблема	Что проверить
Нет входящих запросов	Адрес доступен из интернета, DNS указывает на нужный сервер, сервер передаёт всю цепочку TLS-сертификата
Обработчик отвечает 401 или 403	Имя HTTP-заголовка и значение токена совпадают с данными подключения
HRlink повторяет события	Обработчик возвращает точный статус 200 OK и не закрывает соединение раньше ответа
Бизнес-действие выполняется несколько раз	id события используется как уникальный ключ
Приходят события разных клиентов	Обработчик учитывает clientId, если поле присутствует, и не отклоняет событие без clientId
Доставка прекратилась после длительных ошибок	Обратитесь в Службу заботы, чтобы проверить подписку