> ## Documentation Index
> Fetch the complete documentation index at: https://docs.anivahealth.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Вебхуки

> Отримуй HTTPS-запит від Aniva, коли змінюється запис, замовлення набору для домашнього тесту, його результати, завантажений документ, локація, профіль або відправлення

Вебхук — це HTTPS-запит `POST`, який Aniva надсилає на твій сервер, коли щось змінюється. Тобі не
потрібно робити опитування.

Події компактні. Вони містять ID об’єкта, новий статус, ревізію та `url` для читання. Вони
ніколи не містять лабораторних показників або персональних даних. Прочитай `url` зі своїм API-ключем, щоб отримати дані.

## Швидке налаштування

1. Створи HTTPS-ендпоінт, який приймає `POST` і відповідає `2xx` протягом 15 секунд.
2. Зареєструй його за допомогою [Створення вебхука](https://docs.anivahealth.com/uk/api/webhooks/create-webhook.md).
   Збережи `secret` із відповіді. Aniva показує його лише один раз.
3. [Перевір підпис](#perevirka-pidpisu) кожного запиту.
4. Надішли [тестову подію](https://docs.anivahealth.com/uk/api/webhooks/send-test-event.md). Перевір результат у
   [Списку доставок](https://docs.anivahealth.com/uk/api/webhooks/list-deliveries.md).

Твоєму API-ключу потрібен дозвіл `webhooks_manage`. Попроси Aniva додати його. Вебхук належить
API-ключу, який його створив, і один ключ може мати щонайбільше 5 вебхуків.

## Події

Ти отримуєш подію лише для об’єктів, які твій API-ключ може прочитати через відповідний ендпоінт `GET`.
Обери типи за допомогою `enabled_events`. Надішли `["*"]`, щоб отримувати всі типи, зокрема додані пізніше.

| Тип | Коли спрацьовує |
| - | - |
| `appointment.created` | Запис стає видимим для тебе. Надсилається один раз на запис. |
| `appointment.pending` | Запис переходить у статус `pending`. |
| `appointment.confirmed` | Запис переходить у статус `confirmed`. |
| `appointment.blood_drawn` | Запис переходить у статус `blood_drawn`. |
| `appointment.cancelled` | Запис переходить у статус `cancelled`. |
| `appointment.rescheduled` | Змінюється `scheduled_at` або локація. Не надсилається, коли запис у статусі `cancelled`. |
| `appointment.results.updated` | Результати змінюються. |
| `appointment.results.completed` | `status` результатів переходить у `completed`. |
| `appointment.results.fault` | `status` результатів переходить у `fault`. |
| `home_kit_order.created` | Замовлення створено. Надсилається один раз на замовлення. |
| `home_kit_order.pending` | Замовлення переходить у статус `pending`. |
| `home_kit_order.dispatched` | Замовлення переходить у статус `dispatched`. |
| `home_kit_order.activated` | Замовлення переходить у статус `activated`. |
| `home_kit_order.cancelled` | Замовлення переходить у статус `cancelled`. |
| `home_kit_order.results.updated` | Результати змінюються. |
| `home_kit_order.results.completed` | `status` результатів переходить у `completed`. |
| `home_kit_order.results.fault` | `status` результатів переходить у `fault`. |
| `document.results.updated` | Змінюються результати завантаженого тобою документа або документ збережено. `stored` — фінальний статус: `document.results.completed` після нього не надходить. |
| `document.results.completed` | `status` результатів завантаженого тобою документа переходить у `completed`. |
| `document.results.fault` | `status` результатів завантаженого тобою документа переходить у `fault`. |
| `document.deleted` | Завантажений тобою документ видалено. Надсилається на ендпоінти, які отримали його останню подію результатів. Без `url`. |
| `location.created` | Локація стає видимою для тебе: нова, активована або додана до групи, яку ти читаєш. |
| `location.updated` | Змінюється будь-яке поле локації: назва, адреса, вебсайт, години роботи, зображення. |
| `location.deactivated` | Ти більше не можеш читати цю локацію. |
| `location.retail_prices.updated` | Змінюється опублікована ціна панелі або біомаркера в локації. Потрібна область доступу `retail_prices_view`. |
| `profile.created` | Профіль стає видимим для тебе: новий або доданий до групи профілів, яку ти читаєш. |
| `profile.updated` | Змінюється будь-яке поле [Отримати профіль](https://docs.anivahealth.com/uk/api/profiles/get-profile.md). |
| `profile.deleted` | Профіль видалено або ти більше не можеш його читати. |
| `shipment.created` | Відправлення стає видимим для тебе. |
| `shipment.updated` | Змінюється будь-яке поле відправлення: відстеження, сканування, забір, примітки, посилання. |
| `shipment.pending` | Відправлення переходить у статус `pending`. |
| `shipment.in_transit` | Відправлення переходить у статус `in_transit`. |
| `shipment.delivered` | Відправлення переходить у статус `delivered`. |
| `shipment.fault` | Відправлення переходить у статус `fault`. |
| `shipment.cancelled` | Відправлення переходить у статус `cancelled`. |
| `ping` | Ти надсилаєш тестову подію. Надсилається завжди, не входить до `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`.

## Вміст

| Поле | Опис |
| - | - |
| `id` | ID події (UUID). Збігається із заголовком `webhook-id`. Залишається незмінним під час повторних спроб і повторного надсилання. |
| `type` | Тип події, наприклад `appointment.confirmed`. |
| `timestamp` | Коли відбулася зміна, у форматі ISO 8601 UTC. Не час надсилання. |
| `data` | Змінений об’єкт. Структура залежить від типу події. |

### Дані події статусу

| Поле | Опис |
| - | - |
| `object` | `appointment` або `home_kit_order`. |
| `id` | ID запису або замовлення набору для домашнього тесту (UUID). |
| `url` | `/api/v1/appointments/{id}` або `/api/v1/home-kit-orders/{id}`. |
| `status` | Статус після зміни. |
| `previous_status` | Статус до зміни. `null` для `created`. |
| `status_revision` | Лічильник для кожного об’єкта. Зростає з кожною зміною статусу і може пропускати числа. |

```json appointment.confirmed theme={null}
{
  "id": "0b8e6f3a-2c4d-4e7f-9a1b-3c5d7e9f1a2b",
  "type": "appointment.confirmed",
  "timestamp": "2026-10-15T09:12:44.512Z",
  "data": {
    "object": "appointment",
    "id": "c9f3e2a1-7d6b-4c5e-b3a2-1f0e9d8c7b6a",
    "url": "https://anivahealth.com/api/v1/appointments/c9f3e2a1-7d6b-4c5e-b3a2-1f0e9d8c7b6a",
    "status": "confirmed",
    "previous_status": "pending",
    "status_revision": 2
  }
}
```

### Дані події результатів

| Поле | Опис |
| - | - |
| `object` | `appointment`, `home_kit_order` або `document`. |
| `id` | ID запису, замовлення набору для домашнього тесту або документа (UUID). |
| `url` | Маршрут `/results` об’єкта, наприклад `/api/v1/documents/{id}/results`. |
| `results_status` | `in_progress`, `completed` або `fault`. Для документа також можливе значення `stored`. |
| `previous_results_status` | `results_status` попередньої події результатів. `null` для першої. |
| `results_revision` | Лічильник для кожного об’єкта. Зростає з кожною зміною результатів і може пропускати числа. |

```json home_kit_order.results.completed theme={null}
{
  "id": "6d2a9c4e-8f1b-4a3d-b5e7-0c2f4a6b8d1e",
  "type": "home_kit_order.results.completed",
  "timestamp": "2026-10-15T14:03:00.000Z",
  "data": {
    "object": "home_kit_order",
    "id": "d1e2f3a4-5b6c-4d7e-8f9a-0b1c2d3e4f5a",
    "url": "https://anivahealth.com/api/v1/home-kit-orders/d1e2f3a4-5b6c-4d7e-8f9a-0b1c2d3e4f5a/results",
    "results_status": "completed",
    "previous_results_status": "in_progress",
    "results_revision": 4
  }
}
```

### Дані події видалення документа

`document.deleted` містить `object` (`document`), `id`, `previous_results_status` і
`results_revision`. Вона не має `url`, оскільки читати вже нічого.

```json document.deleted theme={null}
{
  "id": "1c9e7a52-3f4b-4d8a-9e61-7b2c5d0f8a14",
  "type": "document.deleted",
  "timestamp": "2026-10-24T09:12:00.000Z",
  "data": {
    "object": "document",
    "id": "f8a1b2c3-d4e5-4f6a-8b8c-9d0e1f2a3b4c",
    "previous_results_status": "completed",
    "results_revision": 3
  }
}
```

### Дані подій локацій, профілів і відправлень

| Поле | Опис |
| - | - |
| `object` | `location`, `profile` або `shipment`. |
| `id` | ID локації чи профілю (UUID) або номер відправлення. |
| `url` | `/api/v1/locations/{id}`, `/api/v1/locations/{id}/retail-prices`, `/api/v1/profiles/{id}` або `/api/v1/shipments/{id}`. Відсутнє в `.deactivated` і `.deleted`. |
| `status` | Лише для відправлень. Статус після зміни. |
| `previous_status` | Лише для відправлень. Статус до зміни. `null` для `shipment.created`. |
| `revision` | Лічильник для кожного об’єкта за всіма його подіями. Може пропускати числа. Події роздрібних цін мають власний лічильник. |

```json shipment.in_transit theme={null}
{
  "id": "3f7c1a2b-9d4e-4b6a-8c5f-2e1d0a9b8c7d",
  "type": "shipment.in_transit",
  "timestamp": "2026-10-16T08:41:12.000Z",
  "data": {
    "object": "shipment",
    "id": "P2610164821",
    "url": "https://anivahealth.com/api/v1/shipments/P2610164821",
    "status": "in_transit",
    "previous_status": "pending",
    "revision": 3
  }
}
```

`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 хвилин.

```typescript Node.js theme={null}
import { createHmac, timingSafeEqual } from 'node:crypto';

export function verifyAnivaWebhook(rawBody: string, headers: Headers, secret: string): boolean {
  const id = headers.get('webhook-id') ?? '';
  const timestamp = headers.get('webhook-timestamp') ?? '';
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;

  const key = Buffer.from(secret.slice('whsec_'.length), 'base64');
  const expected = createHmac('sha256', key).update(`${id}.${timestamp}.${rawBody}`).digest();

  return (headers.get('webhook-signature') ?? '').split(' ').some((entry) => {
    const [version, signature = ''] = entry.split(',');
    const received = Buffer.from(signature, 'base64');
    return (
      version === 'v1' && received.length === expected.length && timingSafeEqual(received, expected)
    );
  });
}
```

Ця схема — [Standard Webhooks](https://www.standardwebhooks.com). Бібліотеки Standard Webhooks
існують для більшості мов і виконують це за один виклик.

### Ротація секрету

Виклич [Змінити секрет](https://docs.anivahealth.com/uk/api/webhooks/rotate-secret.md), щоб отримати новий секрет. Протягом 24 годин Aniva
підписує старим і новим секретом, тож розгорни новий за цей час. Після витоку надішли
`revoke_current_secret_now: true`, щоб одразу припинити дію старого секрету.

## Доставка

* Відповідай `2xx` протягом 15 секунд. Збережи подію або постав її в чергу та оброби пізніше.
* Використовуй `https` URL на порту 443 із публічним хостом. Aniva не переходить за перенаправленнями: `3xx`
  вважається збоєм.
* Доставка відбувається щонайменше раз і в довільному порядку. Відкидай дублікати за `webhook-id`. Використовуй ревізії, щоб
  ігнорувати старішу подію.
* Відповідай `410 Gone`, щоб зупинити події. Aniva одразу вимикає вебхук.
* Aniva зберігає доставки протягом 30 днів. Після цього ти не зможеш отримати їхній список або надіслати їх повторно.

### Повторні спроби

Відповідь не `2xx`, таймаут або мережева помилка запускає повторну спробу. Кожна подія отримує до 10 спроб
приблизно протягом трьох днів:

| Спроба | Час після першої спроби |
| - | - |
| 2 | приблизно 5 секунд |
| 3 | приблизно 5 хвилин |
| 4 | приблизно 35 хвилин |
| 5 | приблизно 2,5 години |
| 6 | приблизно 7,5 години |
| 7 | приблизно 17,5 години |
| 8 | приблизно 27,5 години |
| 9 | приблизно 51,5 години |
| 10 | приблизно 75,5 години |

Після 10-ї спроби доставка має статус `failed`. Надішли її знову через
[Повторно надіслати доставку](https://docs.anivahealth.com/uk/api/webhooks/resend-delivery.md). Вона зберігає той самий `webhook-id`.

### Сповіщення про збої

Aniva надсилає лист на `alert_emails` вебхука, коли протягом 24 годин не було жодної успішної доставки, коли подія має статус
`failed` і коли вебхук вимкнено. Після 5 днів без успішної доставки Aniva
вимикає вебхук. Вимкнений вебхук не отримує нових подій, а його доставки в очікуванні
скасовуються.

| `disabled_reason` | Причина |
| - | - |
| `Disabled by the partner` | З твого боку надіслано `status: "disabled"`. |
| `Disabled by Aniva` | Aniva вимкнула вебхук. Увімкнути його знову може лише Aniva. |
| `The endpoint answered 410 Gone` | Твій ендпоінт відповів `410 Gone`. |
| `No successful delivery for 5 days` | Протягом 5 днів не було жодної успішної доставки. |

Щоб почати знову, виправ свій ендпоінт і надішли `status: "enabled"` через
[Оновити вебхук](https://docs.anivahealth.com/uk/api/webhooks/update-webhook.md). Пропущені події не надсилаються
повторно самі по собі. Надішли їх повторно або прочитай поточний стан через ендпоінти `GET`.

## Повторні читання

Aniva ненадовго зберігає відповідь деяких ендпоінтів `GET`. Коли твій API-ключ надсилає той самий
запит знову протягом цього часу, ти отримуєш збережену відповідь. Ти не отримуєш помилки, і тіло має той
самий формат.

* **Окремий об’єкт** (відправлення, замовлення набору для домашнього тесту, запис і результати двох останніх):
  під час кожного виклику Aniva перевіряє, чи не змінився об’єкт. Якщо він змінився, ти отримуєш свіжу відповідь.
* **Список** може бути старішим за свої об’єкти щонайбільше на 5 хвилин.

Щоб дізнатися про зміну одразу, використовуй події вебхука з таблиці.

| Ендпоінт | Зберігається | Події, що повідомляють про зміну |
| - | - | - |
| [Отримати відправлення](https://docs.anivahealth.com/uk/api/shipments/get-shipment.md) | 60 хвилин | `shipment.created`, `shipment.updated` |
| [Список відправлень](https://docs.anivahealth.com/uk/api/shipments/list-shipments.md) | 5 хвилин | `shipment.created`, `shipment.updated` |
| [Отримати замовлення набору для домашнього тесту](https://docs.anivahealth.com/uk/api/home-kit-orders/get-home-kit.md) | 60 хвилин | `home_kit_order.created` і по одній події на кожен статус, наприклад `home_kit_order.activated` |
| [Отримати результати замовлення набору для домашнього тесту](https://docs.anivahealth.com/uk/api/home-kit-orders/get-results.md) | 60 хвилин | `home_kit_order.results.updated`, `.completed`, `.fault` |
| [Список замовлень наборів для домашнього тесту](https://docs.anivahealth.com/uk/api/home-kit-orders/list-home-kits.md) | 5 хвилин | ті самі події, що й для одного замовлення набору для домашнього тесту |
| [Отримати запис](https://docs.anivahealth.com/uk/api/appointments/get-appointment.md) | 15 хвилин | `appointment.created`, `appointment.rescheduled` і по одній події на кожен статус, наприклад `appointment.confirmed` |
| [Отримати результати запису](https://docs.anivahealth.com/uk/api/appointments/get-results.md) | 60 хвилин | `appointment.results.updated`, `.completed`, `.fault` |
| [Список записів](https://docs.anivahealth.com/uk/api/appointments/list-appointments.md) | 5 хвилин | ті самі події, що й для одного запису |
| [Список профілів](https://docs.anivahealth.com/uk/api/profiles/list-profiles.md) | 5 хвилин | `profile.created`, `profile.updated`, `profile.deleted` |

* Той самий запит — це той самий API-ключ, той самий ендпоінт і ті самі параметри запиту. Інша
  сторінка списку — це інший запит, і вона отримує власну відповідь.
* Aniva зберігає лише відповідь `200`. Помилка ніколи не зберігається.
* Відлік часу починається, коли Aniva зберігає відповідь. Наступний виклик не подовжує його.
* Після того як твій API-ключ щось створює, оновлює, активує або скасовує, твоє наступне читання буде свіжим.
  Наступне читання цього об’єкта з іншим твоїм API-ключем також буде свіжим.
* У збереженій відповіді про відправлення поля `synced_at` і `updated_at` можуть бути старішими, ніж у
  свіжій відповіді. Статус, відстеження та адреси актуальні.
* У збереженій відповіді з результатами назва біомаркера, одиниця вимірювання або конвертоване значення можуть бути застарілими до 60
  хвилин після того, як Aniva змінить свій каталог. Виміряні значення актуальні.
* Після того як Aniva створює подію вебхука для твого вебхука, твоє наступне читання цього об’єкта, його
  результатів і його списків буде свіжим. Отже, читання після події завжди показує зміну.

### Заголовки відповіді

Кожна відповідь цих ендпоінтів на дійсний API-ключ містить такі заголовки:

| Заголовок | Надсилається з | Значення |
| - | - | - |
| `Aniva-Webhook-Events` | Кожною відповіддю | Події вебхука, що охоплюють ендпоінт, розділені комами. |
| `Link` | Кожною відповіддю | Адреса цієї сторінки з `rel="help"`. |
| `Cache-Status` | Відповіддю `200` | `Aniva; hit; ttl=3476` — збережена відповідь. `ttl` — кількість секунд до того, як стане доступною свіжа відповідь. `Aniva; fwd=miss; stored; ttl=3600` — свіжа відповідь, яку Aniva щойно зберегла. `Aniva; fwd=miss` — свіжа відповідь, яку Aniva не зберегла. |
| `Age` | Збереженою відповіддю | Вік збереженої відповіді в секундах. |
| `Cache-Control` | Відповіддю `200` | `private, no-cache`. Не зберігай відповідь у власному кеші замість виклику Aniva. |

```http theme={null}
HTTP/1.1 200 OK
Age: 124
Cache-Status: Aniva; hit; ttl=3476
Cache-Control: private, no-cache
Aniva-Webhook-Events: shipment.created, shipment.updated
Link: <https://docs.anivahealth.com/concepts/webhooks>; rel="help"
```

## Найкращі практики

* **Відкидай дублікати.** Пропускай подію, `webhook-id` якої вже оброблено.
* **Використовуй ревізії.** Зберігай найвищі значення `status_revision`, `results_revision` і `revision`
  для кожного об’єкта. Ігноруй подію з нижчим значенням.
* **Запитуй `url`.** Подія повідомляє, що щось змінилося. Ендпоінт `GET` повідомляє, що саме.
* **Відповідай швидко.** Став подію в чергу та відповідай `2xx`, перш ніж обробляти її.
* **Звіряй дані.** Запускай регулярне завдання, яке читає відкриті об’єкти через ендпоінти `GET`. Опитування залишається
  робочим запасним варіантом. Повторне читання може повернути збережену відповідь, див. [Повторні читання](#povtorni-chitannya).
* **Тестуй після кожного розгортання.** Використовуй [Надіслати тестову подію](https://docs.anivahealth.com/uk/api/webhooks/send-test-event.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.