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

# Webhook-uri

> Primești un apel HTTPS de la Aniva când se modifică o programare, o comandă de kit de testare la domiciliu, rezultatele acesteia, un document încărcat, o locație, un profil sau o expediere

Un webhook este o cerere HTTPS `POST` pe care Aniva o trimite către serverul tău când se schimbă ceva. Nu trebuie
să faci polling.

Evenimentele sunt minimale. Conțin ID-ul obiectului, noul status, o revizie și `url` de citit. Nu
conțin niciodată valori de laborator sau date personale. Citește `url` cu cheia ta API pentru a obține datele.

## Configurare rapidă

1. Creează un endpoint HTTPS care acceptă `POST` și răspunde cu `2xx` în cel mult 15 secunde.
2. Înregistrează-l cu [Creare webhook](https://docs.anivahealth.com/ro/api/webhooks/create-webhook.md).
   Păstrează `secret` din răspuns. Aniva îl afișează o singură dată.
3. [Verifică semnătura](#verifica-semnatura) fiecărei cereri.
4. Trimite un [eveniment de test](https://docs.anivahealth.com/ro/api/webhooks/send-test-event.md). Verifică rezultatul în
   [Listare livrări](https://docs.anivahealth.com/ro/api/webhooks/list-deliveries.md).

Cheia ta API are nevoie de scope-ul `webhooks_manage`. Cere echipei Aniva să îl adauge. Un webhook aparține
cheii API care l-a creat, iar o cheie poate deține cel mult 5 webhookuri.

## Evenimente

Primești un eveniment doar pentru obiectele pe care cheia ta API le poate citi cu endpointul `GET` corespunzător.
Alege tipurile cu `enabled_events`. Trimite `["*"]` ca să primești toate tipurile, inclusiv pe cele adăugate ulterior.

| Tip | Când se declanșează |
| - | - |
| `appointment.created` | Programarea devine vizibilă pentru tine. Trimis o singură dată per programare. |
| `appointment.pending` | Programarea trece în `pending`. |
| `appointment.confirmed` | Programarea trece în `confirmed`. |
| `appointment.blood_drawn` | Programarea trece în `blood_drawn`. |
| `appointment.cancelled` | Programarea trece în `cancelled`. |
| `appointment.rescheduled` | `scheduled_at` sau locația se schimbă. Nu se trimite când programarea este `cancelled`. |
| `appointment.results.updated` | Rezultatele se schimbă. |
| `appointment.results.completed` | Câmpul `status` al rezultatelor trece în `completed`. |
| `appointment.results.fault` | Câmpul `status` al rezultatelor trece în `fault`. |
| `home_kit_order.created` | Comanda este creată. Trimis o singură dată per comandă. |
| `home_kit_order.pending` | Comanda trece în `pending`. |
| `home_kit_order.dispatched` | Comanda trece în `dispatched`. |
| `home_kit_order.activated` | Comanda trece în `activated`. |
| `home_kit_order.cancelled` | Comanda trece în `cancelled`. |
| `home_kit_order.results.updated` | Rezultatele se schimbă. |
| `home_kit_order.results.completed` | Câmpul `status` al rezultatelor trece în `completed`. |
| `home_kit_order.results.fault` | Câmpul `status` al rezultatelor trece în `fault`. |
| `document.results.updated` | Rezultatele unui document încărcat de tine se schimbă sau acesta este stocat. `stored` este final: nu urmează niciun `document.results.completed`. |
| `document.results.completed` | Câmpul `status` al rezultatelor unui document încărcat de tine trece în `completed`. |
| `document.results.fault` | Câmpul `status` al rezultatelor unui document încărcat de tine trece în `fault`. |
| `document.deleted` | Un document încărcat de tine este șters. Trimis către endpointurile care au primit ultimul său eveniment de rezultate. Fără `url`. |
| `location.created` | Locația devine vizibilă pentru tine: nouă, activată sau adăugată într-un grup pe care îl citești. |
| `location.updated` | Orice câmp al locației se schimbă: nume, adresă, site web, program de lucru, imagine. |
| `location.deactivated` | Nu mai poți citi locația. |
| `location.retail_prices.updated` | Prețul publicat al unui panel sau biomarker din locație se schimbă. Necesită scope-ul `retail_prices_view`. |
| `profile.created` | Profilul devine vizibil pentru tine: nou sau adăugat într-un grup de profiluri pe care îl citești. |
| `profile.updated` | Orice câmp din [Obține profilul](https://docs.anivahealth.com/ro/api/profiles/get-profile.md) se schimbă. |
| `profile.deleted` | Profilul este șters sau nu îl mai poți citi. |
| `shipment.created` | Expedierea devine vizibilă pentru tine. |
| `shipment.updated` | Orice câmp al expedierii se schimbă: urmărire, scanări, ridicare, note, linkuri. |
| `shipment.pending` | Expedierea trece în `pending`. |
| `shipment.in_transit` | Expedierea trece în `in_transit`. |
| `shipment.delivered` | Expedierea trece în `delivered`. |
| `shipment.fault` | Expedierea trece în `fault`. |
| `shipment.cancelled` | Expedierea trece în `cancelled`. |
| `ping` | Ai trimis un eveniment de test. Se trimite întotdeauna, nu face parte din `enabled_events`. |

* Un eveniment de status se declanșează la fiecare trecere în acel status, inclusiv la o revenire. De exemplu, un kit care
  trece din `dispatched` înapoi în `pending` trimite `home_kit_order.pending`.
* O singură modificare poate trimite două evenimente cu același `status_revision`, de exemplu
  `appointment.confirmed` și `appointment.rescheduled`.
* `results.updated` se declanșează la fiecare modificare a rezultatelor: o valoare nouă, o corecție, o eroare, un document
  nou sau înlocuit ori o probă care părăsește obiectul. Sosește în câteva minute de la
  ultima modificare.
* `results.completed` și `results.fault` vin întotdeauna împreună cu un `results.updated` cu același
  `results_revision`. Rezultatele se pot redeschide și finaliza din nou, așa că poți primi un al doilea
  `results.completed`.

Abonează-te la `results.updated` ca să afișezi rezultate parțiale sau la `results.completed` ca să acționezi doar pe
rezultatele finale.

`results.completed` urmărește valorile rezultatelor, nu PDF-ul. PDF-ul raportului poate sosi înainte sau
după valori. Unele laboratoare trimit mai întâi un PDF preliminar și îl înlocuiesc ulterior cu cel final
sub același `id` de document. Înlocuirea trimite `results.updated`. Citește
`documents[].original_file_name` ca să le deosebești: Labor Quade termină un raport preliminar
(Vorbefund) în `_V` și raportul final (Endbefund) în `_E`, de exemplu
`7642100312_B0012_FA_E.pdf`.

Evenimentele pentru locații, profiluri și expedieri sosesc în câteva minute. Aniva așteaptă până când obiectul nu
s-a mai schimbat timp de 2 minute, astfel încât o serie de modificări trimite un singur eveniment. Se aplică și aceste reguli:

* Profilurile anonime nu trimit evenimente.
* O expediere nu trimite niciun eveniment când pierzi accesul la ea.
* O schimbare de status a expedierii trimite `shipment.updated` și evenimentul `shipment.<status>` cu același
  `revision`.

## Payload

| Câmp | Descriere |
| - | - |
| `id` | ID-ul evenimentului (UUID). Egal cu headerul `webhook-id`. Rămâne la fel la reîncercare și retrimitere. |
| `type` | Tipul evenimentului, de exemplu `appointment.confirmed`. |
| `timestamp` | Momentul în care a avut loc modificarea, în format ISO 8601 UTC. Nu momentul trimiterii. |
| `data` | Obiectul modificat. Structura depinde de tipul evenimentului. |

### Datele evenimentului de status

| Câmp | Descriere |
| - | - |
| `object` | `appointment` sau `home_kit_order`. |
| `id` | ID-ul programării sau al comenzii de kit de testare la domiciliu (UUID). |
| `url` | `/api/v1/appointments/{id}` sau `/api/v1/home-kit-orders/{id}`. |
| `status` | Statusul după modificare. |
| `previous_status` | Statusul înainte de modificare. `null` la `created`. |
| `status_revision` | Contor per obiect. Crește la fiecare schimbare de status și poate sări numere. |

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

### Datele evenimentului de rezultate

| Câmp | Descriere |
| - | - |
| `object` | `appointment`, `home_kit_order` sau `document`. |
| `id` | ID-ul programării, al comenzii de kit de testare la domiciliu sau al documentului (UUID). |
| `url` | Ruta `/results` a obiectului, de ex. `/api/v1/documents/{id}/results`. |
| `results_status` | `in_progress`, `completed` sau `fault`. Un document poate fi și `stored`. |
| `previous_results_status` | `results_status` din evenimentul de rezultate anterior. `null` la primul eveniment. |
| `results_revision` | Contor per obiect. Crește la fiecare modificare a rezultatelor și poate sări numere. |

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

### Datele evenimentului de ștergere a documentului

`document.deleted` conține `object` (`document`), `id`, `previous_results_status` și
`results_revision`. Nu are `url`, pentru că nu mai rămâne nimic de citit.

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

### Datele evenimentelor de locație, profil și expediere

| Câmp | Descriere |
| - | - |
| `object` | `location`, `profile` sau `shipment`. |
| `id` | ID-ul locației sau al profilului (UUID) ori referința expedierii. |
| `url` | `/api/v1/locations/{id}`, `/api/v1/locations/{id}/retail-prices`, `/api/v1/profiles/{id}` sau `/api/v1/shipments/{id}`. Lipsește la `.deactivated` și `.deleted`. |
| `status` | Doar pentru expedieri. Statusul după modificare. |
| `previous_status` | Doar pentru expedieri. Statusul înainte de modificare. `null` la `shipment.created`. |
| `revision` | Contor per obiect pentru toate evenimentele sale. Poate sări numere. Evenimentele pentru prețurile de retail au propriul contor. |

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

Un `ping` conține `data.object` `webhook` și `data.id`, ID-ul webhookului.

## Verifică semnătura

Evenimentele nu conțin date, dar ar trebui totuși să îl verifici pe fiecare. O semnătură validă dovedește că
evenimentul provine de la Aniva. Fiecare cerere include headerele `webhook-id`, `webhook-timestamp` (secunde
Unix) și `webhook-signature`.

1. Ia corpul brut al cererii. Verifică-l înainte să parsezi JSON-ul.
2. Construiește conținutul semnat `{webhook-id}.{webhook-timestamp}.{raw body}`.
3. Decodează din base64 partea secretului tău de după `whsec_`. Folosește-o ca cheie.
4. Calculează HMAC-SHA256 pentru conținutul semnat și codifică-l în base64.
5. Compară-l în timp constant cu fiecare intrare `v1,<signature>` din `webhook-signature`. Intrările
   sunt separate prin spații. O singură potrivire este suficientă.
6. Respinge cererea când `webhook-timestamp` diferă cu mai mult de 5 minute față de ceasul tău.

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

Schema este [Standard Webhooks](https://www.standardwebhooks.com). Există biblioteci Standard Webhooks
pentru majoritatea limbajelor și fac asta într-un singur apel.

### Rotește secretul

Apelează [Rotește secretul](https://docs.anivahealth.com/ro/api/webhooks/rotate-secret.md) pentru a obține un secret nou. Timp de 24 de ore, Aniva
semnează atât cu secretul vechi, cât și cu cel nou, așa că implementează-l pe cel nou în acest interval. După o scurgere, trimite
`revoke_current_secret_now: true` pentru a opri imediat secretul vechi.

## Livrare

* Răspunde cu `2xx` în cel mult 15 secunde. Stochează evenimentul sau pune-l în coadă și procesează-l mai târziu.
* Folosește un URL `https` pe portul 443 cu un host public. Aniva nu urmărește redirecționările: un răspuns `3xx`
  contează ca eșec.
* Livrarea se face cel puțin o dată și neordonat. Elimină duplicatele după `webhook-id`. Folosește reviziile pentru a
  ignora un eveniment mai vechi.
* Răspunde cu `410 Gone` pentru a opri evenimentele. Aniva dezactivează imediat webhook-ul.
* Aniva păstrează livrările timp de 30 de zile. După aceea, nu le mai poți lista sau retrimite.

### Reîncercări

Un răspuns diferit de `2xx`, un timeout sau o eroare de rețea declanșează o reîncercare. Fiecare eveniment are până la 10 încercări
pe parcursul a aproximativ trei zile:

| Încercare | Timp de la prima încercare |
| - | - |
| 2 | aproximativ 5 secunde |
| 3 | aproximativ 5 minute |
| 4 | aproximativ 35 de minute |
| 5 | aproximativ 2,5 ore |
| 6 | aproximativ 7,5 ore |
| 7 | aproximativ 17,5 ore |
| 8 | aproximativ 27,5 ore |
| 9 | aproximativ 51,5 ore |
| 10 | aproximativ 75,5 ore |

După încercarea 10, livrarea devine `failed`. Trimite-o din nou cu
[Retrimite livrarea](https://docs.anivahealth.com/ro/api/webhooks/resend-delivery.md). Păstrează același `webhook-id`.

### Notificări de eșec

Aniva trimite un e-mail la adresele din `alert_emails` ale webhook-ului atunci când nicio livrare nu a reușit timp de 24 de ore, când un eveniment este
`failed` și când webhook-ul este dezactivat. După 5 zile fără o livrare reușită, Aniva
dezactivează webhook-ul. Un webhook dezactivat nu primește evenimente noi, iar livrările sale în așteptare sunt
anulate.

| `disabled_reason` | Cauză |
| - | - |
| `Disabled by the partner` | Ai trimis `status: "disabled"`. |
| `Disabled by Aniva` | Aniva a dezactivat webhook-ul. Doar Aniva îl poate reactiva. |
| `The endpoint answered 410 Gone` | Endpoint-ul tău a răspuns cu `410 Gone`. |
| `No successful delivery for 5 days` | Nicio livrare nu a reușit timp de 5 zile. |

Pentru a reporni, remediază endpoint-ul și trimite `status: "enabled"` cu
[Actualizează webhook-ul](https://docs.anivahealth.com/ro/api/webhooks/update-webhook.md). Evenimentele pierdute nu sunt retrimise
automat. Retrimite-le sau citește starea curentă cu endpoint-urile `GET`.

## Citiri repetate

Aniva stochează răspunsul unor endpoint-uri `GET` pentru o perioadă scurtă. Când cheia ta API trimite aceeași
cerere din nou în acest interval, primești răspunsul stocat. Nu primești nicio eroare, iar corpul răspunsului are
același format.

* **O singură înregistrare** (o expediere, o comandă de kit de testare la domiciliu, o programare și rezultatele ultimelor două):
  la fiecare apel, Aniva verifică dacă înregistrarea a rămas neschimbată. Dacă s-a schimbat, primești un răspuns nou.
* **O listă** poate fi mai veche decât înregistrările sale, cu cel mult 5 minute.

Pentru a afla imediat despre o modificare, folosește evenimentele webhook din tabel.

| Endpoint | Durată de stocare | Evenimente care te anunță despre o modificare |
| - | - | - |
| [Obține expedierea](https://docs.anivahealth.com/ro/api/shipments/get-shipment.md) | 60 de minute | `shipment.created`, `shipment.updated` |
| [Listează expedierile](https://docs.anivahealth.com/ro/api/shipments/list-shipments.md) | 5 minute | `shipment.created`, `shipment.updated` |
| [Obține comanda de kit de testare la domiciliu](https://docs.anivahealth.com/ro/api/home-kit-orders/get-home-kit.md) | 60 de minute | `home_kit_order.created` și câte un eveniment pentru fiecare status, de exemplu `home_kit_order.activated` |
| [Obține rezultatele comenzii de kit de testare la domiciliu](https://docs.anivahealth.com/ro/api/home-kit-orders/get-results.md) | 60 de minute | `home_kit_order.results.updated`, `.completed`, `.fault` |
| [Listează comenzile de kit de testare la domiciliu](https://docs.anivahealth.com/ro/api/home-kit-orders/list-home-kits.md) | 5 minute | aceleași evenimente ca pentru o singură comandă de kit de testare la domiciliu |
| [Obține programarea](https://docs.anivahealth.com/ro/api/appointments/get-appointment.md) | 15 minute | `appointment.created`, `appointment.rescheduled` și câte un eveniment pentru fiecare status, de exemplu `appointment.confirmed` |
| [Obține rezultatele programării](https://docs.anivahealth.com/ro/api/appointments/get-results.md) | 60 de minute | `appointment.results.updated`, `.completed`, `.fault` |
| [Listează programările](https://docs.anivahealth.com/ro/api/appointments/list-appointments.md) | 5 minute | aceleași evenimente ca pentru o singură programare |
| [Listează profilurile](https://docs.anivahealth.com/ro/api/profiles/list-profiles.md) | 5 minute | `profile.created`, `profile.updated`, `profile.deleted` |

* Aceeași cerere înseamnă aceeași cheie API, același endpoint și aceiași parametri de interogare. O altă
  pagină a unei liste este o altă cerere și primește propriul răspuns.
* Aniva stochează doar un răspuns `200`. O eroare nu este stocată niciodată.
* Intervalul începe în momentul în care Aniva stochează răspunsul. Un apel ulterior nu îl prelungește.
* După ce cheia ta API creează, actualizează, activează sau anulează ceva, următoarea ta citire este nouă.
  Și următoarea citire a acelei înregistrări cu o altă cheie API a ta este nouă.
* Într-un răspuns stocat pentru o expediere, câmpurile `synced_at` și `updated_at` pot fi mai vechi decât într-un
  răspuns nou. Statusul, urmărirea și adresele sunt actuale.
* Într-un răspuns stocat pentru rezultate, numele unui biomarker, o unitate de măsură sau o valoare convertită pot fi mai vechi cu până la 60
  de minute după ce Aniva își modifică catalogul. Valorile măsurate sunt actuale.
* După ce Aniva creează un eveniment webhook pentru webhook-ul tău, următoarea ta citire a acelei înregistrări, a
  rezultatelor sale și a listelor sale este nouă. Astfel, citirea care urmează unui eveniment arată întotdeauna modificarea.

### Antete de răspuns

Fiecare răspuns al acestor endpoint-uri pentru o cheie API validă conține aceste antete:

| Antet | Trimis cu | Semnificație |
| - | - | - |
| `Aniva-Webhook-Events` | Fiecare răspuns | Evenimentele webhook care acoperă endpoint-ul, separate prin virgulă. |
| `Link` | Fiecare răspuns | Adresa acestei pagini, cu `rel="help"`. |
| `Cache-Status` | Un răspuns `200` | `Aniva; hit; ttl=3476` este un răspuns stocat. `ttl` este numărul de secunde până când este disponibil un răspuns nou. `Aniva; fwd=miss; stored; ttl=3600` este un răspuns nou pe care Aniva l-a stocat acum. `Aniva; fwd=miss` este un răspuns nou pe care Aniva nu l-a stocat. |
| `Age` | Un răspuns stocat | Vechimea răspunsului stocat, în secunde. |
| `Cache-Control` | Un răspuns `200` | `private, no-cache`. Nu păstra răspunsul într-un cache propriu în locul unui apel către 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"
```

## Bune practici

* **Elimină duplicatele.** Sari peste un eveniment al cărui `webhook-id` l-ai procesat deja.
* **Folosește reviziile.** Stochează cele mai mari valori pentru `status_revision`, `results_revision` și `revision`
  per obiect. Ignoră un eveniment cu o valoare mai mică.
* **Interoghează `url`.** Evenimentul indică faptul că ceva s-a schimbat. Endpoint-ul `GET` spune ce anume.
* **Răspunde rapid.** Pune evenimentul în coadă și răspunde cu `2xx` înainte să îl procesezi.
* **Reconciliază.** Rulează un job periodic care citește obiectele deschise cu endpoint-urile `GET`. Polling-ul rămâne o
  soluție de rezervă validă. O citire repetată poate primi un răspuns stocat, vezi [Citiri repetate](#citiri-repetate).
* **Testează după fiecare deploy.** Folosește [Trimite eveniment de test](https://docs.anivahealth.com/ro/api/webhooks/send-test-event.md).


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