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

# Webhooks

> Få et HTTPS-kall fra Aniva når en time, en bestilling av hjemmetestsett, resultatene fra den, et opplastet dokument, et sted, en profil eller en forsendelse endres

En webhook er en HTTPS-`POST` som Aniva sender til serveren din når noe endres. Du trenger ikke
å polle.

Hendelser er tynne. De inneholder objekt-ID-en, den nye statusen, en revisjon og `url`-en du skal lese. De
inneholder aldri labverdier eller personopplysninger. Les `url`-en med API-nøkkelen din for å hente dataene.

## Raskt oppsett

1. Bygg et HTTPS-endepunkt som godtar `POST` og svarer med `2xx` innen 15 sekunder.
2. Registrer det med [Opprett webhook](https://docs.anivahealth.com/no/api/webhooks/create-webhook.md).
   Lagre `secret` fra svaret. Aniva viser den bare én gang.
3. [Verifiser signaturen](#verifiser-signaturen) for hver forespørsel.
4. Send en [testhendelse](https://docs.anivahealth.com/no/api/webhooks/send-test-event.md). Sjekk resultatet i
   [Vis leveringer](https://docs.anivahealth.com/no/api/webhooks/list-deliveries.md).

API-nøkkelen din trenger scopet `webhooks_manage`. Be Aniva om å legge det til. En webhook tilhører
API-nøkkelen som opprettet den, og en nøkkel kan eie maksimalt 5 webhooks.

## Hendelser

Du mottar bare en hendelse for objekter API-nøkkelen din kan lese med det tilsvarende `GET`-endepunktet.
Velg typene med `enabled_events`. Send `["*"]` for å motta alle typer, også typer som legges til senere.

| Type | Når den utløses |
| - | - |
| `appointment.created` | Timen blir synlig for deg. Sendes én gang per time. |
| `appointment.pending` | Timen går over til `pending`. |
| `appointment.confirmed` | Timen går over til `confirmed`. |
| `appointment.blood_drawn` | Timen går over til `blood_drawn`. |
| `appointment.cancelled` | Timen går over til `cancelled`. |
| `appointment.rescheduled` | `scheduled_at` eller stedet endres. Sendes ikke når timen er `cancelled`. |
| `appointment.results.updated` | Resultatene endres. |
| `appointment.results.completed` | Resultatenes `status` går over til `completed`. |
| `appointment.results.fault` | Resultatenes `status` går over til `fault`. |
| `home_kit_order.created` | Bestillingen opprettes. Sendes én gang per bestilling. |
| `home_kit_order.pending` | Bestillingen går over til `pending`. |
| `home_kit_order.dispatched` | Bestillingen går over til `dispatched`. |
| `home_kit_order.activated` | Bestillingen går over til `activated`. |
| `home_kit_order.cancelled` | Bestillingen går over til `cancelled`. |
| `home_kit_order.results.updated` | Resultatene endres. |
| `home_kit_order.results.completed` | Resultatenes `status` går over til `completed`. |
| `home_kit_order.results.fault` | Resultatenes `status` går over til `fault`. |
| `document.results.updated` | Resultatene for et dokument du lastet opp endres, eller det lagres. `stored` er endelig: ingen `document.results.completed` følger. |
| `document.results.completed` | Resultatenes `status` for et dokument du lastet opp går over til `completed`. |
| `document.results.fault` | Resultatenes `status` for et dokument du lastet opp går over til `fault`. |
| `document.deleted` | Et dokument du lastet opp slettes. Sendes til endepunktene som mottok den siste resultathendelsen for dokumentet. Ingen `url`. |
| `location.created` | Stedet blir synlig for deg: nytt, aktivert eller lagt til i en gruppe du leser. |
| `location.updated` | Et felt for stedet endres: navn, adresse, nettsted, åpningstider, bilde. |
| `location.deactivated` | Du kan ikke lenger lese stedet. |
| `location.retail_prices.updated` | En publisert panel- eller biomarkørpris på stedet endres. Krever scopet `retail_prices_view`. |
| `profile.created` | Profilen blir synlig for deg: ny eller lagt til i en profilgruppe du leser. |
| `profile.updated` | Et felt i [Hent profil](https://docs.anivahealth.com/no/api/profiles/get-profile.md) endres. |
| `profile.deleted` | Profilen slettes, eller du kan ikke lenger lese den. |
| `shipment.created` | Forsendelsen blir synlig for deg. |
| `shipment.updated` | Et felt for forsendelsen endres: sporing, skanninger, henting, notater, lenker. |
| `shipment.pending` | Forsendelsen går over til `pending`. |
| `shipment.in_transit` | Forsendelsen går over til `in_transit`. |
| `shipment.delivered` | Forsendelsen går over til `delivered`. |
| `shipment.fault` | Forsendelsen går over til `fault`. |
| `shipment.cancelled` | Forsendelsen går over til `cancelled`. |
| `ping` | Du sendte en testhendelse. Sendes alltid, ikke en del av `enabled_events`. |

* En statushendelse utløses ved hver overgang til den statusen, også ved en overgang tilbake. For eksempel sender et hjemmetestsett som
  går fra `dispatched` tilbake til `pending`, `home_kit_order.pending`.
* Én endring kan sende to hendelser med samme `status_revision`, for eksempel
  `appointment.confirmed` og `appointment.rescheduled`.
* `results.updated` utløses ved hver endring i resultatene: en ny verdi, en rettelse, en feil, et nytt
  eller erstattet dokument, eller en prøve som forlater objektet. Den kommer innen noen få minutter etter den
  siste endringen.
* `results.completed` og `results.fault` kommer alltid sammen med en `results.updated` med samme
  `results_revision`. Resultater kan åpnes igjen og fullføres på nytt, så du kan få enda en
  `results.completed`.

Abonner på `results.updated` for å vise delresultater, eller på `results.completed` for bare å reagere på
endelige resultater.

`results.completed` følger resultatverdiene, ikke PDF-en. Rapport-PDF-en kan komme før eller
etter verdiene. Noen laboratorier sender først en foreløpig PDF og erstatter den senere med den endelige
under samme dokument-`id`. Erstatningen sender `results.updated`. Les
`documents[].original_file_name` for å skille dem fra hverandre: Labor Quade avslutter en foreløpig rapport
(Vorbefund) med `_V` og den endelige rapporten (Endbefund) med `_E`, for eksempel
`7642100312_B0012_FA_E.pdf`.

Hendelser for sted, profil og forsendelse kommer innen noen få minutter. Aniva venter til objektet ikke
har blitt endret på 2 minutter, slik at flere raske endringer sender én hendelse. Disse reglene gjelder også:

* Anonyme profiler sender ingen hendelser.
* En forsendelse sender ingen hendelse når du mister tilgang til den.
* En statusendring for en forsendelse sender `shipment.updated` og `shipment.<status>`-hendelsen med samme
  `revision`.

## Payload

| Felt | Beskrivelse |
| - | - |
| `id` | Hendelses-ID (UUID). Lik `webhook-id`-headeren. Forblir den samme ved nytt forsøk og ny sending. |
| `type` | Hendelsestype, for eksempel `appointment.confirmed`. |
| `timestamp` | Når endringen skjedde, som et ISO 8601 UTC-tidspunkt. Ikke tidspunktet for utsendelsen. |
| `data` | Det endrede objektet. Strukturen avhenger av hendelsestypen. |

### Data for statushendelser

| Felt | Beskrivelse |
| - | - |
| `object` | `appointment` eller `home_kit_order`. |
| `id` | ID-en (UUID) for timen eller bestillingen av hjemmetestsett. |
| `url` | `/api/v1/appointments/{id}` eller `/api/v1/home-kit-orders/{id}`. |
| `status` | Statusen etter endringen. |
| `previous_status` | Statusen før endringen. `null` ved `created`. |
| `status_revision` | Teller per objekt. Den øker ved hver statusendring og kan hoppe over tall. |

```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 for resultathendelser

| Felt | Beskrivelse |
| - | - |
| `object` | `appointment`, `home_kit_order` eller `document`. |
| `id` | ID-en (UUID) for timen, bestillingen av hjemmetestsett eller dokumentet. |
| `url` | `/results`-ruten til objektet, f.eks. `/api/v1/documents/{id}/results`. |
| `results_status` | `in_progress`, `completed` eller `fault`. Et dokument kan også være `stored`. |
| `previous_results_status` | `results_status` fra forrige resultathendelse. `null` ved den første. |
| `results_revision` | Teller per objekt. Den øker ved hver resultatendring og kan hoppe over tall. |

```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 for hendelser ved slettet dokument

`document.deleted` inneholder `object` (`document`), `id`, `previous_results_status` og
`results_revision`. Den har ingen `url`, fordi det ikke er noe igjen å lese.

```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 for steds-, profil- og forsendelseshendelser

| Felt | Beskrivelse |
| - | - |
| `object` | `location`, `profile` eller `shipment`. |
| `id` | Steds- eller profil-ID-en (UUID), eller forsendelsesreferansen. |
| `url` | `/api/v1/locations/{id}`, `/api/v1/locations/{id}/retail-prices`, `/api/v1/profiles/{id}` eller `/api/v1/shipments/{id}`. Utelates ved `.deactivated` og `.deleted`. |
| `status` | Bare forsendelser. Statusen etter endringen. |
| `previous_status` | Bare forsendelser. Statusen før endringen. `null` ved `shipment.created`. |
| `revision` | Teller per objekt på tvers av alle hendelsene for det. Den kan hoppe over tall. Hendelser for utsalgspriser har sin egen teller. |

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

En `ping` inneholder `data.object` `webhook` og `data.id`, webhook-ID-en.

## Verifiser signaturen

Hendelser inneholder ingen data, men du bør likevel verifisere hver enkelt. En gyldig signatur beviser at
hendelsen kom fra Aniva. Hver forespørsel inneholder headerne `webhook-id`, `webhook-timestamp`
(Unix-sekunder) og `webhook-signature`.

1. Ta den rå forespørselskroppen. Verifiser den før du parser JSON-en.
2. Sett sammen det signerte innholdet `{webhook-id}.{webhook-timestamp}.{raw body}`.
3. Base64-dekod delen av hemmeligheten din etter `whsec_`. Bruk den som nøkkel.
4. Beregn HMAC-SHA256 av det signerte innholdet og kod det som base64.
5. Sammenlign det i konstant tid med hver `v1,<signature>`-oppføring i `webhook-signature`. Oppføringene
   er skilt med mellomrom. Ett treff er nok.
6. Avvis forespørselen når `webhook-timestamp` avviker med mer enn 5 minutter fra klokken din.

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

Standarden er [Standard Webhooks](https://www.standardwebhooks.com). Det finnes Standard Webhooks-biblioteker
for de fleste språk som gjør dette i ett kall.

### Roter hemmeligheten

Kall [Roter hemmelighet](https://docs.anivahealth.com/no/api/webhooks/rotate-secret.md) for å få en ny hemmelighet. I 24 timer
signerer Aniva med både den gamle og den nye hemmeligheten, så ta i bruk den nye innen den tiden. Etter en lekkasje sender du
`revoke_current_secret_now: true` for å stoppe den gamle hemmeligheten med én gang.

## Levering

* Svar `2xx` innen 15 sekunder. Lagre hendelsen eller legg den i kø, og gjør arbeidet senere.
* Bruk en `https`-URL på port 443 med en offentlig vert. Aniva følger ikke omdirigeringer: et `3xx`-svar
  regnes som en feil.
* Levering skjer minst én gang og i vilkårlig rekkefølge. Forkast duplikater ved hjelp av `webhook-id`. Bruk revisjonene til å
  ignorere en eldre hendelse.
* Svar `410 Gone` for å stoppe hendelsene. Aniva deaktiverer webhooken med én gang.
* Aniva lagrer leveringer i 30 dager. Etter det kan du ikke liste dem opp eller sende dem på nytt.

### Nye forsøk

Et svar som ikke er `2xx`, et tidsavbrudd eller en nettverksfeil starter et nytt forsøk. Hver hendelse får opptil 10 forsøk
over omtrent tre dager:

| Forsøk | Tid etter første forsøk |
| - | - |
| 2 | omtrent 5 sekunder |
| 3 | omtrent 5 minutter |
| 4 | omtrent 35 minutter |
| 5 | omtrent 2,5 timer |
| 6 | omtrent 7,5 timer |
| 7 | omtrent 17,5 timer |
| 8 | omtrent 27,5 timer |
| 9 | omtrent 51,5 timer |
| 10 | omtrent 75,5 timer |

Etter forsøk 10 er leveringen `failed`. Send den på nytt med
[Send levering på nytt](https://docs.anivahealth.com/no/api/webhooks/resend-delivery.md). Den beholder samme `webhook-id`.

### Feilvarsler

Aniva sender e-post til webhookens `alert_emails` når ingen levering har lyktes på 24 timer, når en hendelse er
`failed`, og når webhooken deaktiveres. Etter 5 dager uten en vellykket levering deaktiverer
Aniva webhooken. En deaktivert webhook får ingen nye hendelser, og de ventende leveringene
kanselleres.

| `disabled_reason` | Årsak |
| - | - |
| `Disabled by the partner` | Du sendte `status: "disabled"`. |
| `Disabled by Aniva` | Aniva deaktiverte webhooken. Bare Aniva kan aktivere den igjen. |
| `The endpoint answered 410 Gone` | Endepunktet ditt svarte `410 Gone`. |
| `No successful delivery for 5 days` | Ingen levering lyktes på 5 dager. |

For å starte igjen fikser du endepunktet ditt og sender `status: "enabled"` med
[Oppdater webhook](https://docs.anivahealth.com/no/api/webhooks/update-webhook.md). Hendelser du gikk glipp av, sendes ikke
på nytt av seg selv. Send dem på nytt, eller les gjeldende tilstand med `GET`-endepunktene.

## Gjentatte lesinger

Aniva lagrer svaret fra enkelte `GET`-endepunkter i en kort periode. Når API-nøkkelen din sender samme
forespørsel på nytt innenfor denne tiden, får du det lagrede svaret. Du får ingen feil, og svarkroppen har samme
format.

* **Én oppføring** (en forsendelse, en bestilling av hjemmetestsett, en time og resultatene av de to siste):
  ved hvert kall sjekker Aniva at oppføringen er uendret. Hvis den er endret, får du et ferskt svar.
* **En liste** kan være eldre enn oppføringene den inneholder, høyst 5 minutter.

For å få vite om en endring med én gang, bruker du webhook-hendelsene i tabellen.

| Endepunkt | Lagret i | Hendelser som varsler deg om en endring |
| - | - | - |
| [Hent forsendelse](https://docs.anivahealth.com/no/api/shipments/get-shipment.md) | 60 minutter | `shipment.created`, `shipment.updated` |
| [List opp forsendelser](https://docs.anivahealth.com/no/api/shipments/list-shipments.md) | 5 minutter | `shipment.created`, `shipment.updated` |
| [Hent bestilling av hjemmetestsett](https://docs.anivahealth.com/no/api/home-kit-orders/get-home-kit.md) | 60 minutter | `home_kit_order.created` og én hendelse per status, for eksempel `home_kit_order.activated` |
| [Hent resultater for bestilling av hjemmetestsett](https://docs.anivahealth.com/no/api/home-kit-orders/get-results.md) | 60 minutter | `home_kit_order.results.updated`, `.completed`, `.fault` |
| [List opp bestillinger av hjemmetestsett](https://docs.anivahealth.com/no/api/home-kit-orders/list-home-kits.md) | 5 minutter | de samme hendelsene som for én bestilling av hjemmetestsett |
| [Hent time](https://docs.anivahealth.com/no/api/appointments/get-appointment.md) | 15 minutter | `appointment.created`, `appointment.rescheduled` og én hendelse per status, for eksempel `appointment.confirmed` |
| [Hent resultater for time](https://docs.anivahealth.com/no/api/appointments/get-results.md) | 60 minutter | `appointment.results.updated`, `.completed`, `.fault` |
| [List opp timer](https://docs.anivahealth.com/no/api/appointments/list-appointments.md) | 5 minutter | de samme hendelsene som for én time |
| [List opp profiler](https://docs.anivahealth.com/no/api/profiles/list-profiles.md) | 5 minutter | `profile.created`, `profile.updated`, `profile.deleted` |

* Samme forespørsel betyr samme API-nøkkel, samme endepunkt og samme spørringsparametere. En annen
  side i en liste er en annen forespørsel og får sitt eget svar.
* Aniva lagrer bare `200`-svar. En feil lagres aldri.
* Tiden starter når Aniva lagrer svaret. Et senere kall forlenger den ikke.
* Etter at API-nøkkelen din oppretter, oppdaterer, aktiverer eller kansellerer noe, er neste lesing fersk.
  Neste lesing av den oppføringen med en annen av dine API-nøkler er også fersk.
* I et lagret forsendelsessvar kan feltene `synced_at` og `updated_at` være eldre enn i et
  ferskt svar. Status, sporing og adresser er oppdaterte.
* I et lagret resultatsvar kan et biomarkørnavn, en enhet eller en omregnet verdi være opptil 60
  minutter gammel etter at Aniva endrer katalogen sin. De målte verdiene er oppdaterte.
* Etter at Aniva oppretter en webhook-hendelse for webhooken din, er neste lesing av den oppføringen, av
  resultatene dens og av listene dens fersk. Dermed viser lesingen som følger etter en hendelse, alltid endringen.

### Svarheadere

Hvert svar fra disse endepunktene til en gyldig API-nøkkel har disse headerne:

| Header | Sendt med | Betydning |
| - | - | - |
| `Aniva-Webhook-Events` | Hvert svar | Webhook-hendelsene som dekker endepunktet, skilt med komma. |
| `Link` | Hvert svar | Adressen til denne siden, med `rel="help"`. |
| `Cache-Status` | Et `200`-svar | `Aniva; hit; ttl=3476` er et lagret svar. `ttl` er antall sekunder til et ferskt svar er tilgjengelig. `Aniva; fwd=miss; stored; ttl=3600` er et ferskt svar som Aniva lagret nå. `Aniva; fwd=miss` er et ferskt svar som Aniva ikke lagret. |
| `Age` | Et lagret svar | Alderen på det lagrede svaret i sekunder. |
| `Cache-Control` | Et `200`-svar | `private, no-cache`. Ikke lagre svaret i en egen cache i stedet for å kalle 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"
```

## Beste praksis

* **Forkast duplikater.** Hopp over hendelser med en `webhook-id` du allerede har behandlet.
* **Bruk revisjonene.** Lagre den høyeste verdien av `status_revision`, `results_revision` og `revision`
  per objekt. Ignorer hendelser med en lavere verdi.
* **Hent `url`.** Hendelsen sier at noe er endret. `GET`-endepunktet sier hva.
* **Svar raskt.** Legg hendelsen i kø og svar `2xx` før du behandler den.
* **Avstem.** Kjør en fast jobb som leser åpne objekter med `GET`-endepunktene. Polling er fortsatt en
  gyldig reserveløsning. En gjentatt lesing kan få et lagret svar, se [Gjentatte lesinger](#gjentatte-lesinger).
* **Test etter hver utrulling.** Bruk [Send testhendelse](https://docs.anivahealth.com/no/api/webhooks/send-test-event.md).


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