> ## 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 отправляет на твой сервер, когда что-то меняется. Тебе не
нужно опрашивать API.

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

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

1. Создай HTTPS-эндпоинт, который принимает `POST` и отвечает статусом `2xx` в течение 15 секунд.
2. Зарегистрируй его через [Создание вебхука](https://docs.anivahealth.com/ru/api/webhooks/create-webhook.md).
   Сохрани `secret` из ответа. Aniva показывает его только один раз.
3. [Проверяй подпись](#proverka-podpisi) каждого запроса.
4. Отправь [тестовое событие](https://docs.anivahealth.com/ru/api/webhooks/send-test-event.md). Проверь результат в
   [Списке доставок](https://docs.anivahealth.com/ru/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` | Меняется любое поле [Get Profile](https://docs.anivahealth.com/ru/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/ru/api/webhooks/rotate-secret.md), чтобы получить новый секрет. В течение 24 часов Aniva
подписывает запросы старым и новым секретом, поэтому разверни новый за это время. После утечки отправь
`revoke_current_secret_now: true`, чтобы сразу отключить старый секрет.

## Доставка

* Отвечай `2xx` в течение 15 секунд. Сохрани событие или поставь его в очередь, а обработку выполни позже.
* Используй URL с `https` на порту 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/ru/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/ru/api/webhooks/update-webhook.md). Пропущенные события не отправляются
повторно сами по себе. Отправь их заново или получи актуальное состояние через эндпоинты `GET`.

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

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

* **Один объект** (отправка, заказ набора для домашнего теста, запись и результаты двух последних):
  при каждом вызове Aniva проверяет, не изменился ли объект. Если он изменился, ты получаешь свежий ответ.
* **Список** может быть старше своих объектов максимум на 5 минут.

Чтобы сразу узнавать об изменениях, используй события вебхука из таблицы.

| Эндпоинт | Время хранения | События, сообщающие об изменении |
| - | - | - |
| [Получить отправку](https://docs.anivahealth.com/ru/api/shipments/get-shipment.md) | 60 минут | `shipment.created`, `shipment.updated` |
| [Список отправок](https://docs.anivahealth.com/ru/api/shipments/list-shipments.md) | 5 минут | `shipment.created`, `shipment.updated` |
| [Получить заказ набора для домашнего теста](https://docs.anivahealth.com/ru/api/home-kit-orders/get-home-kit.md) | 60 минут | `home_kit_order.created` и по одному событию на каждый статус, например `home_kit_order.activated` |
| [Получить результаты заказа набора для домашнего теста](https://docs.anivahealth.com/ru/api/home-kit-orders/get-results.md) | 60 минут | `home_kit_order.results.updated`, `.completed`, `.fault` |
| [Список заказов наборов для домашнего теста](https://docs.anivahealth.com/ru/api/home-kit-orders/list-home-kits.md) | 5 минут | те же события, что и для одного заказа набора для домашнего теста |
| [Получить запись](https://docs.anivahealth.com/ru/api/appointments/get-appointment.md) | 15 минут | `appointment.created`, `appointment.rescheduled` и по одному событию на каждый статус, например `appointment.confirmed` |
| [Получить результаты записи](https://docs.anivahealth.com/ru/api/appointments/get-results.md) | 60 минут | `appointment.results.updated`, `.completed`, `.fault` |
| [Список записей](https://docs.anivahealth.com/ru/api/appointments/list-appointments.md) | 5 минут | те же события, что и для одной записи |
| [Список профилей](https://docs.anivahealth.com/ru/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`. Опрос остаётся
  рабочим запасным вариантом. Повторное чтение может вернуть сохранённый ответ, см. [Повторные чтения](#povtornye-chteniya).
* **Тестируй после каждого развёртывания.** Используй [Отправить тестовое событие](https://docs.anivahealth.com/ru/api/webhooks/send-test-event.md).


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