> ## 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.

# Webhooky

> Přijímej HTTPS volání od Aniva, když se změní termín, objednávka domácí testovací sady, její výsledky, nahraný dokument, lokalita, profil nebo zásilka

Webhook je HTTPS požadavek `POST`, který Aniva pošle na tvůj server, když se něco změní. Nemusíš
se pravidelně dotazovat.

Události jsou úsporné. Obsahují ID objektu, nový stav, revizi a `url` pro načtení. Nikdy
neobsahují laboratorní hodnoty ani osobní údaje. Data získáš načtením `url` pomocí svého API klíče.

## Rychlé nastavení

1. Vytvoř HTTPS endpoint, který přijímá `POST` a odpoví `2xx` do 15 sekund.
2. Zaregistruj ho pomocí [Vytvořit webhook](https://docs.anivahealth.com/cs/api/webhooks/create-webhook.md).
   Ulož si `secret` z odpovědi. Aniva ho zobrazí jen jednou.
3. [Ověř podpis](#overeni-podpisu) každého požadavku.
4. Pošli [testovací událost](https://docs.anivahealth.com/cs/api/webhooks/send-test-event.md). Výsledek zkontroluj v
   [Seznamu doručení](https://docs.anivahealth.com/cs/api/webhooks/list-deliveries.md).

Tvůj API klíč potřebuje scope `webhooks_manage`. Požádej Aniva o jeho přidání. Webhook patří
API klíči, který ho vytvořil, a jeden klíč může vlastnit nejvýše 5 webhooků.

## Události

Událost dostaneš jen pro objekty, které tvůj API klíč může číst přes odpovídající `GET` endpoint.
Typy vyber pomocí `enabled_events`. Pošli `["*"]`, pokud chceš dostávat všechny typy, i ty přidané později.

| Typ | Kdy se spustí |
| - | - |
| `appointment.created` | Termín se pro tebe stane viditelným. Odešle se jednou za termín. |
| `appointment.pending` | Termín přejde do stavu `pending`. |
| `appointment.confirmed` | Termín přejde do stavu `confirmed`. |
| `appointment.blood_drawn` | Termín přejde do stavu `blood_drawn`. |
| `appointment.cancelled` | Termín přejde do stavu `cancelled`. |
| `appointment.rescheduled` | Změní se `scheduled_at` nebo lokalita. Neodesílá se, když je termín ve stavu `cancelled`. |
| `appointment.results.updated` | Výsledky se změní. |
| `appointment.results.completed` | `status` výsledků přejde do `completed`. |
| `appointment.results.fault` | `status` výsledků přejde do `fault`. |
| `home_kit_order.created` | Objednávka se vytvoří. Odešle se jednou za objednávku. |
| `home_kit_order.pending` | Objednávka přejde do stavu `pending`. |
| `home_kit_order.dispatched` | Objednávka přejde do stavu `dispatched`. |
| `home_kit_order.activated` | Objednávka přejde do stavu `activated`. |
| `home_kit_order.cancelled` | Objednávka přejde do stavu `cancelled`. |
| `home_kit_order.results.updated` | Výsledky se změní. |
| `home_kit_order.results.completed` | `status` výsledků přejde do `completed`. |
| `home_kit_order.results.fault` | `status` výsledků přejde do `fault`. |
| `document.results.updated` | Změní se výsledky tvého nahraného dokumentu, nebo se dokument uloží. `stored` je konečný stav: žádné `document.results.completed` nenásleduje. |
| `document.results.completed` | `status` výsledků tvého nahraného dokumentu přejde do `completed`. |
| `document.results.fault` | `status` výsledků tvého nahraného dokumentu přejde do `fault`. |
| `document.deleted` | Smaže se tvůj nahraný dokument. Odešle se na endpointy, které dostaly jeho poslední událost výsledků. Bez `url`. |
| `location.created` | Lokalita se pro tebe stane viditelnou: nová, aktivovaná nebo přidaná do skupiny, kterou čteš. |
| `location.updated` | Změní se jakékoli pole lokality: název, adresa, web, otevírací doba, obrázek. |
| `location.deactivated` | Lokalitu už nemůžeš číst. |
| `location.retail_prices.updated` | Změní se zveřejněná cena panelu nebo biomarkeru v lokalitě. Vyžaduje scope `retail_prices_view`. |
| `profile.created` | Profil se pro tebe stane viditelným: nový nebo přidaný do skupiny profilů, kterou čteš. |
| `profile.updated` | Změní se jakékoli pole z [Získat profil](https://docs.anivahealth.com/cs/api/profiles/get-profile.md). |
| `profile.deleted` | Profil se smaže, nebo ho už nemůžeš číst. |
| `shipment.created` | Zásilka se pro tebe stane viditelnou. |
| `shipment.updated` | Změní se jakékoli pole zásilky: sledování, skeny, vyzvednutí, poznámky, odkazy. |
| `shipment.pending` | Zásilka přejde do stavu `pending`. |
| `shipment.in_transit` | Zásilka přejde do stavu `in_transit`. |
| `shipment.delivered` | Zásilka přejde do stavu `delivered`. |
| `shipment.fault` | Zásilka přejde do stavu `fault`. |
| `shipment.cancelled` | Zásilka přejde do stavu `cancelled`. |
| `ping` | Pošleš testovací událost. Vždy se odešle, není součástí `enabled_events`. |

* Stavová událost se spustí při každém přechodu do daného stavu, i při přechodu zpět. Například sada, která přejde z `dispatched` zpět do `pending`, pošle `home_kit_order.pending`.
* Jedna změna může poslat dvě události se stejným `status_revision`, například `appointment.confirmed` a `appointment.rescheduled`.
* `results.updated` se spustí při každé změně výsledků: nová hodnota, oprava, chyba, nový nebo nahrazený dokument nebo vzorek, který objekt opustí. Dorazí během několika minut od poslední změny.
* `results.completed` a `results.fault` vždy přijdou společně s `results.updated` se stejným `results_revision`. Výsledky se mohou znovu otevřít a znovu dokončit, takže můžeš dostat druhé `results.completed`.

Přihlas se k odběru `results.updated` pro zobrazení částečných výsledků, nebo k `results.completed`, pokud chceš reagovat jen na finální výsledky.

`results.completed` se řídí hodnotami výsledků, ne PDF. PDF se zprávou může dorazit před hodnotami i po nich. Některé laboratoře nejdřív pošlou předběžné PDF a později ho pod stejným `id` dokumentu nahradí finálním. Nahrazení pošle `results.updated`. Podle `documents[].original_file_name` je rozlišíš: u Labor Quade končí předběžná zpráva (Vorbefund) na `_V` a finální zpráva (Endbefund) na `_E`, například `7642100312_B0012_FA_E.pdf`.

Události lokalit, profilů a zásilek dorazí během několika minut. Aniva čeká, až se objekt 2 minuty nezmění, takže série úprav pošle jednu událost. Platí také tato pravidla:

* Anonymní profily neposílají žádné události.
* Zásilka nepošle žádnou událost, když k ní ztratíš přístup.
* Změna stavu zásilky pošle `shipment.updated` a událost `shipment.<status>` se stejným `revision`.

## Payload

| Pole | Popis |
| - | - |
| `id` | ID události (UUID). Odpovídá hlavičce `webhook-id`. Zůstává stejné při opakovaném pokusu i opětovném odeslání. |
| `type` | Typ události, například `appointment.confirmed`. |
| `timestamp` | Kdy ke změně došlo, ve formátu ISO 8601 UTC. Ne čas odeslání. |
| `data` | Změněný objekt. Struktura závisí na typu události. |

### Data stavové události

| Pole | Popis |
| - | - |
| `object` | `appointment` nebo `home_kit_order`. |
| `id` | ID termínu nebo objednávky domácí testovací sady (UUID). |
| `url` | `/api/v1/appointments/{id}` nebo `/api/v1/home-kit-orders/{id}`. |
| `status` | Stav po změně. |
| `previous_status` | Stav před změnou. `null` při `created`. |
| `status_revision` | Počítadlo pro každý objekt. S každou změnou stavu roste a může přeskakovat čísla. |

```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
  }
}
```

### Data události výsledků

| Pole | Popis |
| - | - |
| `object` | `appointment`, `home_kit_order` nebo `document`. |
| `id` | ID termínu, objednávky domácí testovací sady nebo dokumentu (UUID). |
| `url` | Cesta `/results` daného objektu, např. `/api/v1/documents/{id}/results`. |
| `results_status` | `in_progress`, `completed` nebo `fault`. Dokument může mít také `stored`. |
| `previous_results_status` | `results_status` předchozí události výsledků. `null` u první události. |
| `results_revision` | Počítadlo pro každý objekt. S každou změnou výsledků roste a může přeskakovat čísla. |

```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
  }
}
```

### Data události smazání dokumentu

`document.deleted` obsahuje `object` (`document`), `id`, `previous_results_status` a `results_revision`. Nemá žádné `url`, protože už není co číst.

```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
  }
}
```

### Data událostí lokalit, profilů a zásilek

| Pole | Popis |
| - | - |
| `object` | `location`, `profile` nebo `shipment`. |
| `id` | ID lokality nebo profilu (UUID), případně reference zásilky. |
| `url` | `/api/v1/locations/{id}`, `/api/v1/locations/{id}/retail-prices`, `/api/v1/profiles/{id}` nebo `/api/v1/shipments/{id}`. Chybí u `.deactivated` a `.deleted`. |
| `status` | Jen u zásilek. Stav po změně. |
| `previous_status` | Jen u zásilek. Stav před změnou. `null` při `shipment.created`. |
| `revision` | Počítadlo pro každý objekt napříč všemi jeho událostmi. Může přeskakovat čísla. Události maloobchodních cen mají vlastní počítadlo. |

```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
  }
}
```

Událost `ping` obsahuje `data.object` `webhook` a `data.id`, tedy ID webhooku.

## Ověření podpisu

Události neobsahují žádná data, přesto je dobré každou z nich ověřit. Platný podpis dokazuje, že událost poslala Aniva. Každý požadavek obsahuje hlavičky `webhook-id`, `webhook-timestamp` (Unix sekundy) a `webhook-signature`.

1. Vezmi nezpracované tělo požadavku. Ověř ho ještě před parsováním JSON.
2. Sestav podepsaný obsah `{webhook-id}.{webhook-timestamp}.{raw body}`.
3. Dekóduj z base64 část svého tajného klíče za `whsec_`. Použij ji jako klíč.
4. Spočítej HMAC-SHA256 podepsaného obsahu a zakóduj ho do base64.
5. Porovnej ho v konstantním čase s každou položkou `v1,<signature>` v `webhook-signature`. Položky jsou oddělené mezerami. Stačí jedna shoda.
6. Odmítni požadavek, pokud se `webhook-timestamp` liší od tvých hodin o více než 5 minut.

```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)
    );
  });
}
```

Jde o schéma [Standard Webhooks](https://www.standardwebhooks.com). Knihovny Standard Webhooks existují pro většinu jazyků a zvládnou to jedním voláním.

### Rotace tajného klíče

Voláním [Rotovat tajný klíč](https://docs.anivahealth.com/cs/api/webhooks/rotate-secret.md) získáš nový tajný klíč. Po dobu 24 hodin Aniva
podepisuje starým i novým tajným klíčem, takže nový nasaď během této doby. Po úniku pošli
`revoke_current_secret_now: true` a starý tajný klíč hned přestane platit.

## Doručování

* Odpověz `2xx` do 15 sekund. Událost ulož nebo zařaď do fronty a zpracuj ji později.
* Použij `https` URL na portu 443 s veřejným hostitelem. Aniva nesleduje přesměrování: `3xx`
  se počítá jako selhání.
* Doručování probíhá alespoň jednou a bez zaručeného pořadí. Duplicity zahazuj podle `webhook-id`. Pomocí revizí
  ignoruj starší událost.
* Pro zastavení událostí odpověz `410 Gone`. Aniva webhook hned vypne.
* Aniva uchovává doručení 30 dní. Poté je už nemůžeš vypsat ani znovu odeslat.

### Opakované pokusy

Odpověď jiná než `2xx`, vypršení času nebo chyba sítě spustí opakovaný pokus. Každá událost má až 10 pokusů
během zhruba tří dnů:

| Pokus | Čas po prvním pokusu |
| - | - |
| 2 | asi 5 sekund |
| 3 | asi 5 minut |
| 4 | asi 35 minut |
| 5 | asi 2,5 hodiny |
| 6 | asi 7,5 hodiny |
| 7 | asi 17,5 hodiny |
| 8 | asi 27,5 hodiny |
| 9 | asi 51,5 hodiny |
| 10 | asi 75,5 hodiny |

Po 10. pokusu má doručení stav `failed`. Pošli ho znovu pomocí
[Znovu odeslat doručení](https://docs.anivahealth.com/cs/api/webhooks/resend-delivery.md). Ponechá si stejné `webhook-id`.

### Upozornění na selhání

Aniva pošle e-mail na adresy v `alert_emails` webhooku, když se za 24 hodin žádné doručení nepodaří, když je událost
ve stavu `failed` a když se webhook vypne. Po 5 dnech bez úspěšného doručení Aniva
webhook vypne. Vypnutý webhook nedostává žádné nové události a jeho čekající doručení se
zruší.

| `disabled_reason` | Příčina |
| - | - |
| `Disabled by the partner` | Přišlo od tebe `status: "disabled"`. |
| `Disabled by Aniva` | Aniva webhook vypnula. Znovu ho může zapnout jen Aniva. |
| `The endpoint answered 410 Gone` | Tvůj endpoint odpověděl `410 Gone`. |
| `No successful delivery for 5 days` | Žádné doručení se 5 dní nepodařilo. |

Pokud chceš začít znovu, oprav svůj endpoint a pošli `status: "enabled"` pomocí
[Aktualizovat webhook](https://docs.anivahealth.com/cs/api/webhooks/update-webhook.md). Zmeškané události se samy znovu
nepošlou. Pošli je znovu, nebo si aktuální stav načti přes `GET` endpointy.

## Opakovaná čtení

Aniva na krátkou dobu ukládá odpověď některých `GET` endpointů. Když tvůj API klíč během této doby
pošle stejný požadavek znovu, dostaneš uloženou odpověď. Nedostaneš žádnou chybu a tělo má
stejný formát.

* **Jeden záznam** (zásilka, objednávka domácí testovací sady, termín a výsledky posledních dvou):
  při každém volání Aniva zkontroluje, jestli se záznam nezměnil. Pokud se změnil, dostaneš čerstvou odpověď.
* **Seznam** může být starší než jeho záznamy, nejvýše o 5 minut.

Pokud se chceš o změně dozvědět hned, použij události webhooku z tabulky.

| Endpoint | Doba uložení | Události, které tě upozorní na změnu |
| - | - | - |
| [Získat zásilku](https://docs.anivahealth.com/cs/api/shipments/get-shipment.md) | 60 minut | `shipment.created`, `shipment.updated` |
| [Vypsat zásilky](https://docs.anivahealth.com/cs/api/shipments/list-shipments.md) | 5 minut | `shipment.created`, `shipment.updated` |
| [Získat objednávku domácí testovací sady](https://docs.anivahealth.com/cs/api/home-kit-orders/get-home-kit.md) | 60 minut | `home_kit_order.created` a jedna událost pro každý stav, například `home_kit_order.activated` |
| [Získat výsledky objednávky domácí testovací sady](https://docs.anivahealth.com/cs/api/home-kit-orders/get-results.md) | 60 minut | `home_kit_order.results.updated`, `.completed`, `.fault` |
| [Vypsat objednávky domácích testovacích sad](https://docs.anivahealth.com/cs/api/home-kit-orders/list-home-kits.md) | 5 minut | stejné události jako pro jednu objednávku domácí testovací sady |
| [Získat termín](https://docs.anivahealth.com/cs/api/appointments/get-appointment.md) | 15 minut | `appointment.created`, `appointment.rescheduled` a jedna událost pro každý stav, například `appointment.confirmed` |
| [Získat výsledky termínu](https://docs.anivahealth.com/cs/api/appointments/get-results.md) | 60 minut | `appointment.results.updated`, `.completed`, `.fault` |
| [Vypsat termíny](https://docs.anivahealth.com/cs/api/appointments/list-appointments.md) | 5 minut | stejné události jako pro jeden termín |
| [Vypsat profily](https://docs.anivahealth.com/cs/api/profiles/list-profiles.md) | 5 minut | `profile.created`, `profile.updated`, `profile.deleted` |

* Stejný požadavek znamená stejný API klíč, stejný endpoint a stejné parametry dotazu. Jiná
  stránka seznamu je jiný požadavek a dostane vlastní odpověď.
* Aniva ukládá jen odpověď `200`. Chyba se neukládá nikdy.
* Čas začíná běžet ve chvíli, kdy Aniva odpověď uloží. Pozdější volání ho neprodlužuje.
* Poté, co tvůj API klíč něco vytvoří, aktualizuje, aktivuje nebo zruší, bude tvé další čtení čerstvé.
  Čerstvé bude i další čtení tohoto záznamu s jiným tvým API klíčem.
* V uložené odpovědi zásilky mohou být pole `synced_at` a `updated_at` starší než
  v čerstvé odpovědi. Stav, sledování a adresy jsou aktuální.
* V uložené odpovědi s výsledky může být název biomarkeru, jednotka nebo přepočítaná hodnota až 60
  minut stará poté, co Aniva změní svůj katalog. Naměřené hodnoty jsou aktuální.
* Poté, co Aniva vytvoří událost pro tvůj webhook, bude tvé další čtení daného záznamu, jeho
  výsledků i jeho seznamů čerstvé. Čtení po události tak vždy ukáže změnu.

### Hlavičky odpovědi

Každá odpověď těchto endpointů pro platný API klíč obsahuje tyto hlavičky:

| Hlavička | Posílá se s | Význam |
| - | - | - |
| `Aniva-Webhook-Events` | Každou odpovědí | Události webhooku, které se týkají endpointu, oddělené čárkami. |
| `Link` | Každou odpovědí | Adresa této stránky s `rel="help"`. |
| `Cache-Status` | Odpovědí `200` | `Aniva; hit; ttl=3476` je uložená odpověď. `ttl` je počet sekund do chvíle, kdy bude k dispozici čerstvá odpověď. `Aniva; fwd=miss; stored; ttl=3600` je čerstvá odpověď, kterou Aniva právě uložila. `Aniva; fwd=miss` je čerstvá odpověď, kterou Aniva neuložila. |
| `Age` | Uloženou odpovědí | Stáří uložené odpovědi v sekundách. |
| `Cache-Control` | Odpovědí `200` | `private, no-cache`. Neukládej odpověď do vlastní mezipaměti místo volání 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"
```

## Osvědčené postupy

* **Zahazuj duplicity.** Přeskoč událost s `webhook-id`, které už máš zpracované.
* **Používej revize.** Ukládej nejvyšší `status_revision`, `results_revision` a `revision`
  pro každý objekt. Událost s nižší hodnotou ignoruj.
* **Načítej `url`.** Událost říká, že se něco změnilo. `GET` endpoint říká co.
* **Odpovídej rychle.** Zařaď událost do fronty a odpověz `2xx` dřív, než ji zpracuješ.
* **Synchronizuj stav.** Spouštěj pravidelnou úlohu, která čte otevřené objekty přes `GET` endpointy. Pravidelné dotazování zůstává
  platnou záložní možností. Opakované čtení může vrátit uloženou odpověď, viz [Opakovaná čtení](#opakovana-cteni).
* **Testuj po každém nasazení.** Použij [Odeslat testovací událost](https://docs.anivahealth.com/cs/api/webhooks/send-test-event.md).


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