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