Перейти к основному содержанию
Вебхук — это HTTPS-запрос POST, который Aniva отправляет на твой сервер, когда что-то меняется. Тебе не нужно опрашивать API. События компактные. Они содержат ID объекта, новый статус, ревизию и url для чтения. Они никогда не содержат лабораторных показателей или персональных данных. Прочитай url со своим API-ключом, чтобы получить данные.

Быстрая настройка

  1. Создай HTTPS-эндпоинт, который принимает POST и отвечает статусом 2xx в течение 15 секунд.
  2. Зарегистрируй его через Создание вебхука. Сохрани secret из ответа. Aniva показывает его только один раз.
  3. Проверяй подпись каждого запроса.
  4. Отправь тестовое событие. Проверь результат в Списке доставок.
Твоему API-ключу нужна область доступа webhooks_manage. Попроси Aniva добавить её. Вебхук принадлежит API-ключу, который его создал, и одному ключу может принадлежать не более 5 вебхуков.

События

Ты получаешь событие только для объектов, которые твой API-ключ может прочитать через соответствующий эндпоинт GET. Выбери типы с помощью enabled_events. Отправь ["*"], чтобы получать все типы, в том числе добавленные позже.
  • Событие статуса срабатывает при каждом переходе в этот статус, в том числе при возврате. Например, набор, который переходит из dispatched обратно в pending, отправляет home_kit_order.pending.
  • Одно изменение может отправить два события с одинаковым status_revision, например appointment.confirmed и appointment.rescheduled.
  • results.updated срабатывает при каждом изменении результатов: новое значение, исправление, ошибка, новый или заменённый документ либо образец, который больше не относится к объекту. Оно приходит в течение нескольких минут после последнего изменения.
  • results.completed и results.fault всегда приходят вместе с results.updated с тем же results_revision. Результаты могут открыться повторно и снова завершиться, поэтому ты можешь получить второе results.completed.
Подпишись на results.updated, чтобы показывать частичные результаты, или на results.completed, чтобы реагировать только на финальные результаты. results.completed зависит от значений результатов, а не от PDF. PDF-отчёт может прийти до или после значений. Некоторые лаборатории сначала отправляют предварительный PDF, а позже заменяют его финальным под тем же id документа. При замене отправляется results.updated. Чтобы отличить их, смотри documents[].original_file_name: у Labor Quade предварительный отчёт (Vorbefund) заканчивается на _V, а финальный (Endbefund) — на _E, например 7642100312_B0012_FA_E.pdf. События локаций, профилей и отправлений приходят в течение нескольких минут. Aniva ждёт, пока объект остаётся без изменений 2 минуты, поэтому серия правок отправляет одно событие. Также действуют эти правила:
  • Анонимные профили не отправляют событий.
  • Отправление не отправляет событие, когда ты теряешь к нему доступ.
  • Изменение статуса отправления отправляет shipment.updated и событие shipment.<status> с тем же revision.

Полезная нагрузка

Данные событий статуса

appointment.confirmed

Данные событий о результатах

home_kit_order.results.completed

Данные события удаления документа

document.deleted содержит object (document), id, previous_results_status и results_revision. В нём нет url, потому что читать больше нечего.
document.deleted

Данные событий локаций, профилей и отправлений

shipment.in_transit
Событие ping содержит data.object со значением webhook и data.id — ID вебхука.

Проверка подписи

События не содержат данных, но всё равно стоит проверять каждое из них. Корректная подпись подтверждает, что событие пришло от Aniva. Каждый запрос содержит заголовки webhook-id, webhook-timestamp (секунды Unix) и webhook-signature.
  1. Возьми исходное тело запроса. Проверь его до разбора JSON.
  2. Собери подписываемую строку {webhook-id}.{webhook-timestamp}.{raw body}.
  3. Декодируй из base64 часть твоего секрета после whsec_. Используй её как ключ.
  4. Вычисли HMAC-SHA256 от подписываемой строки и закодируй результат в base64.
  5. Сравни его за константное время с каждым значением v1,<signature> в webhook-signature. Значения разделены пробелами. Одного совпадения достаточно.
  6. Отклони запрос, если webhook-timestamp отличается от твоих часов больше чем на 5 минут.
Node.js
Эта схема — Standard Webhooks. Библиотеки Standard Webhooks есть для большинства языков и делают это за один вызов.

Смена секрета

Вызови Сменить секрет, чтобы получить новый секрет. В течение 24 часов Aniva подписывает запросы старым и новым секретом, поэтому разверни новый за это время. После утечки отправь revoke_current_secret_now: true, чтобы сразу отключить старый секрет.

Доставка

  • Отвечай 2xx в течение 15 секунд. Сохрани событие или поставь его в очередь, а обработку выполни позже.
  • Используй URL с https на порту 443 и публичным хостом. Aniva не переходит по редиректам: ответ 3xx считается ошибкой.
  • Доставка выполняется как минимум один раз и без гарантии порядка. Отбрасывай дубликаты по webhook-id. Используй ревизии, чтобы игнорировать более старые события.
  • Ответь 410 Gone, чтобы остановить отправку событий. Aniva сразу отключит вебхук.
  • Aniva хранит доставки 30 дней. После этого нельзя получить их список или отправить их повторно.

Повторные попытки

Ответ не 2xx, таймаут или сетевая ошибка запускают повторную попытку. Для каждого события выполняется до 10 попыток примерно за три дня: После 10-й попытки доставка получает статус failed. Отправь её снова с помощью Повторно отправить доставку. При этом сохраняется тот же webhook-id.

Уведомления об ошибках

Aniva отправляет письмо на адреса alert_emails вебхука, когда за 24 часа не было ни одной успешной доставки, когда событие получило статус failed и когда вебхук отключён. После 5 дней без успешной доставки Aniva отключает вебхук. Отключённый вебхук не получает новых событий, а его ожидающие доставки отменяются. Чтобы возобновить работу, исправь свой эндпоинт и отправь status: "enabled" через Обновить вебхук. Пропущенные события не отправляются повторно сами по себе. Отправь их заново или получи актуальное состояние через эндпоинты GET.

Повторные чтения

Aniva недолго хранит ответ некоторых эндпоинтов GET. Когда твой API-ключ отправляет тот же запрос повторно в течение этого времени, ты получаешь сохранённый ответ. Ошибки нет, а тело ответа имеет тот же формат.
  • Один объект (отправка, заказ набора для домашнего теста, запись и результаты двух последних): при каждом вызове Aniva проверяет, не изменился ли объект. Если он изменился, ты получаешь свежий ответ.
  • Список может быть старше своих объектов максимум на 5 минут.
Чтобы сразу узнавать об изменениях, используй события вебхука из таблицы.
  • Тот же запрос — это тот же API-ключ, тот же эндпоинт и те же параметры запроса. Другая страница списка — это другой запрос, и для неё возвращается свой ответ.
  • Aniva хранит только ответы 200. Ошибки никогда не сохраняются.
  • Отсчёт времени начинается, когда Aniva сохраняет ответ. Повторный вызов его не продлевает.
  • После того как твой API-ключ создаст, обновит, активирует или отменит что-либо, твоё следующее чтение будет свежим. Следующее чтение этого объекта с другим твоим API-ключом тоже будет свежим.
  • В сохранённом ответе по отправке поля synced_at и updated_at могут быть старше, чем в свежем ответе. Статус, трекинг и адреса актуальны.
  • В сохранённом ответе с результатами название биомаркера, единица измерения или пересчитанное значение могут отставать до 60 минут после того, как Aniva изменит свой каталог. Измеренные значения актуальны.
  • После того как Aniva создаст событие вебхука для твоего вебхука, твоё следующее чтение этого объекта, его результатов и его списков будет свежим. Поэтому чтение после события всегда показывает изменение.

Заголовки ответа

Каждый ответ этих эндпоинтов на запрос с действующим API-ключом содержит такие заголовки:

Рекомендации

  • Отбрасывай дубликаты. Пропускай события, чей webhook-id уже обработан.
  • Используй ревизии. Храни наибольшие status_revision, results_revision и revision для каждого объекта. Игнорируй события с меньшим значением.
  • Запрашивай url. Событие сообщает, что что-то изменилось. Эндпоинт GET сообщает, что именно.
  • Отвечай быстро. Поставь событие в очередь и ответь 2xx до его обработки.
  • Сверяй данные. Запускай регулярную задачу, которая читает открытые объекты через эндпоинты GET. Опрос остаётся рабочим запасным вариантом. Повторное чтение может вернуть сохранённый ответ, см. Повторные чтения.
  • Тестируй после каждого развёртывания. Используй Отправить тестовое событие.