POST, який Aniva надсилає на твій сервер, коли щось змінюється. Тобі не
потрібно робити опитування.
Події компактні. Вони містять 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 секунд. Збережи подію або постав її в чергу та оброби пізніше. - Використовуй
httpsURL на порту 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. Опитування залишається робочим запасним варіантом. Повторне читання може повернути збережену відповідь, див. Повторні читання. - Тестуй після кожного розгортання. Використовуй Надіслати тестову подію.