POST, который Aniva отправляет на твой сервер, когда что-то меняется. Тебе не
нужно опрашивать API.
События компактные. Они содержат ID объекта, новый статус, ревизию и url для чтения. Они
никогда не содержат лабораторных показателей или персональных данных. Прочитай url со своим API-ключом, чтобы получить данные.
Быстрая настройка
- Создай HTTPS-эндпоинт, который принимает
POSTи отвечает статусом2xxв течение 15 секунд. - Зарегистрируй его через Создание вебхука.
Сохрани
secretиз ответа. Aniva показывает его только один раз. - Проверяй подпись каждого запроса.
- Отправь тестовое событие. Проверь результат в Списке доставок.
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.
- Возьми исходное тело запроса. Проверь его до разбора JSON.
- Собери подписываемую строку
{webhook-id}.{webhook-timestamp}.{raw body}. - Декодируй из base64 часть твоего секрета после
whsec_. Используй её как ключ. - Вычисли HMAC-SHA256 от подписываемой строки и закодируй результат в base64.
- Сравни его за константное время с каждым значением
v1,<signature>вwebhook-signature. Значения разделены пробелами. Одного совпадения достаточно. - Отклони запрос, если
webhook-timestampотличается от твоих часов больше чем на 5 минут.
Node.js
Смена секрета
Вызови Сменить секрет, чтобы получить новый секрет. В течение 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. Опрос остаётся рабочим запасным вариантом. Повторное чтение может вернуть сохранённый ответ, см. Повторные чтения. - Тестируй после каждого развёртывания. Используй Отправить тестовое событие.