Уведомления от Yario

Как принимать, проверять и не обрабатывать повторно автоматические HTTP-уведомления Yario.

Результат

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

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

Что отправляет Yario

Для каждого события Yario выполняет POST на согласованный HTTPS-адрес.

Заголовки запроса

X-Yario-Event-Id: 0c8b3c8e-26dd-4f15-a0a7-f5307d443adc
X-Yario-Timestamp: 1784182200
X-Yario-Signature: v1=<hex-hmac>
Content-Type: application/json

Пример события

{
  "eventId": "0c8b3c8e-26dd-4f15-a0a7-f5307d443adc",
  "type": "ticket.message.created",
  "createdAt": "2026-07-16T06:10:00Z",
  "installationId": "5bf6b037-6087-4e70-87e5-cce14774a74d",
  "data": {
    "ticketId": "f5b382ad-d8e7-4c3f-99bb-aa2769d85be1",
    "resource": {
      "messageId": "a2fbeb18-44df-4702-a0e4-e90f42d33221",
      "content": "Документы получены",
      "attachments": [],
      "createdAt": "2026-07-16T06:09:58Z"
    }
  }
}

Обязательно проверьте подпись

Подпись защищает от поддельных запросов. Yario подписывает строку <timestamp>.<raw-body> алгоритмом HMAC-SHA256.

Важно вычислять подпись по исходным байтам тела до преобразования JSON.

Формула подписи

expected = "v1=" + hex(hmac_sha256(secret, timestamp + "." + raw_body))

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

отклонить запрос без обязательных заголовков;
отклонить время события, которое отличается от текущего более чем на 5 минут;
вычислить подпись по исходному телу;
сравнить подписи способом с постоянным временем выполнения;
убедиться, что заголовок X-Yario-Event-Id совпадает с eventId в теле;
сохранить eventId до запуска долгой обработки;
быстро вернуть ответ 2xx.

Какие события существуют

Тип	Что произошло
`ticket.updated`	Менеджер Yario изменил обращение
`ticket.message.created`	В обращении появилось сообщение от Yario
`merchant_onboarding.application.created`	Подготовлена новая анкета мерчанта
`merchant_onboarding.application.updated`	Анкета обновлена после исправлений

В пределах /v1 могут появляться новые типы. Неизвестное событие сохраните для диагностики, отметьте как неподдерживаемое и верните 2xx. Иначе Yario будет без пользы отправлять его повторно.

Почему одно событие может прийти несколько раз

При сетевой ошибке, 408, 429 или ответе 5xx Yario повторяет доставку. Всего возможно до 8 попыток с увеличивающейся задержкой от 5 секунд до 1 часа.

Один eventId может быть доставлен повторно. Храните уже обработанные идентификаторы и не выполняйте одно и то же действие дважды.

Как понять, что всё работает

Проверьте пять сценариев: правильная подпись, повтор того же события, неверная подпись, устаревшее время и неизвестный тип. Готовый пример этих проверок есть в репозитории партнёрской интеграции.

Навигация: начало работы · обзор API · обращения и сообщения · проверка мерчанта · тестирование

Обновлено: 20 июля 2026 г.