> ## 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å ett HTTPS-anrop från Aniva när en bokning, en beställning av hemtestkit, dess resultat, ett uppladdat dokument, en plats, en profil eller en försändelse ändras

En webhook är en HTTPS `POST` som Aniva skickar till din server när något ändras. Du behöver inte
polla.

Händelser är tunna. De innehåller objektets ID, den nya statusen, en revision och den `url` som ska
läsas. De innehåller aldrig labbvärden eller personuppgifter. Läs `url` med din API-nyckel för att
hämta datan.

## Snabbstart

1. Bygg en HTTPS-slutpunkt som tar emot `POST` och svarar med `2xx` inom 15 sekunder.
2. Registrera den med [Skapa webhook](https://docs.anivahealth.com/sv/api/webhooks/create-webhook.md).
   Spara `secret` från svaret. Aniva visar det bara en gång.
3. [Verifiera signaturen](#verifiera-signaturen) för varje begäran.
4. Skicka en [testhändelse](https://docs.anivahealth.com/sv/api/webhooks/send-test-event.md). Kontrollera resultatet i
   [Lista leveranser](https://docs.anivahealth.com/sv/api/webhooks/list-deliveries.md).

Din API-nyckel behöver scopet `webhooks_manage`. Be Aniva att lägga till det. En webhook tillhör den
API-nyckel som skapade den, och en nyckel kan äga högst 5 webhooks.

## Händelser

Du får bara en händelse för objekt som din API-nyckel kan läsa med motsvarande `GET`-endpoint.
Välj typer med `enabled_events`. Skicka `["*"]` för att ta emot alla typer, även typer som läggs till senare.

| Typ | När den utlöses |
| - | - |
| `appointment.created` | Bokningen blir synlig för dig. Skickas en gång per bokning. |
| `appointment.pending` | Bokningen går över till `pending`. |
| `appointment.confirmed` | Bokningen går över till `confirmed`. |
| `appointment.blood_drawn` | Bokningen går över till `blood_drawn`. |
| `appointment.cancelled` | Bokningen går över till `cancelled`. |
| `appointment.rescheduled` | `scheduled_at` eller platsen ändras. Skickas inte när bokningen är `cancelled`. |
| `appointment.results.updated` | Resultaten ändras. |
| `appointment.results.completed` | Resultatens `status` går över till `completed`. |
| `appointment.results.fault` | Resultatens `status` går över till `fault`. |
| `home_kit_order.created` | Beställningen skapas. Skickas en gång per beställning. |
| `home_kit_order.pending` | Beställningen går över till `pending`. |
| `home_kit_order.dispatched` | Beställningen går över till `dispatched`. |
| `home_kit_order.activated` | Beställningen går över till `activated`. |
| `home_kit_order.cancelled` | Beställningen går över till `cancelled`. |
| `home_kit_order.results.updated` | Resultaten ändras. |
| `home_kit_order.results.completed` | Resultatens `status` går över till `completed`. |
| `home_kit_order.results.fault` | Resultatens `status` går över till `fault`. |
| `document.results.updated` | Resultaten för ett dokument du laddat upp ändras, eller så lagras det. `stored` är slutgiltigt: ingen `document.results.completed` följer. |
| `document.results.completed` | Resultatens `status` för ett dokument du laddat upp går över till `completed`. |
| `document.results.fault` | Resultatens `status` för ett dokument du laddat upp går över till `fault`. |
| `document.deleted` | Ett dokument du laddat upp tas bort. Skickas till de endpoints som tog emot dess senaste resultathändelse. Ingen `url`. |
| `location.created` | Platsen blir synlig för dig: ny, aktiverad eller tillagd i en grupp du läser. |
| `location.updated` | Något fält på platsen ändras: namn, adress, webbplats, öppettider, bild. |
| `location.deactivated` | Du kan inte längre läsa platsen. |
| `location.retail_prices.updated` | Ett publicerat pris för en panel eller biomarkör på platsen ändras. Kräver scopet `retail_prices_view`. |
| `profile.created` | Profilen blir synlig för dig: ny eller tillagd i en profilgrupp du läser. |
| `profile.updated` | Något fält i [Hämta profil](https://docs.anivahealth.com/sv/api/profiles/get-profile.md) ändras. |
| `profile.deleted` | Profilen tas bort, eller så kan du inte längre läsa den. |
| `shipment.created` | Försändelsen blir synlig för dig. |
| `shipment.updated` | Något fält på försändelsen ändras: spårning, skanningar, upphämtning, anteckningar, länkar. |
| `shipment.pending` | Försändelsen går över till `pending`. |
| `shipment.in_transit` | Försändelsen går över till `in_transit`. |
| `shipment.delivered` | Försändelsen går över till `delivered`. |
| `shipment.fault` | Försändelsen går över till `fault`. |
| `shipment.cancelled` | Försändelsen går över till `cancelled`. |
| `ping` | Du skickade en testhändelse. Skickas alltid, ingår inte i `enabled_events`. |

* En statushändelse utlöses vid varje övergång till den statusen, även vid en återgång. Ett kit som till exempel
  går från `dispatched` tillbaka till `pending` skickar `home_kit_order.pending`.
* En ändring kan skicka två händelser med samma `status_revision`, till exempel
  `appointment.confirmed` och `appointment.rescheduled`.
* `results.updated` utlöses vid varje ändring av resultaten: ett nytt värde, en rättelse, ett fel, ett nytt
  eller utbytt dokument, eller ett prov som lämnar objektet. Den kommer inom några minuter efter den
  senaste ändringen.
* `results.completed` och `results.fault` kommer alltid tillsammans med en `results.updated` med samma
  `results_revision`. Resultat kan öppnas igen och slutföras på nytt, så du kan få en andra
  `results.completed`.

Prenumerera på `results.updated` för att visa delresultat, eller på `results.completed` för att bara agera på
slutgiltiga resultat.

`results.completed` följer resultatvärdena, inte PDF-filen. Rapportens PDF kan komma före eller
efter värdena. Vissa labb skickar först en preliminär PDF och ersätter den senare med den slutgiltiga
under samma dokument-`id`. Utbytet skickar `results.updated`. Läs
`documents[].original_file_name` för att skilja dem åt: Labor Quade avslutar en preliminär rapport
(Vorbefund) med `_V` och den slutgiltiga rapporten (Endbefund) med `_E`, till exempel
`7642100312_B0012_FA_E.pdf`.

Händelser för platser, profiler och försändelser kommer inom några minuter. Aniva väntar tills objektet inte
har ändrats på 2 minuter, så en följd av ändringar skickar en händelse. Dessa regler gäller också:

* Anonyma profiler skickar inga händelser.
* En försändelse skickar ingen händelse när du förlorar åtkomst till den.
* En statusändring för en försändelse skickar `shipment.updated` och händelsen `shipment.<status>` med samma
  `revision`.

## Payload

| Fält | Beskrivning |
| - | - |
| `id` | Händelse-id (UUID). Samma som headern `webhook-id`. Förblir detsamma vid nytt försök och omsändning. |
| `type` | Händelsetyp, till exempel `appointment.confirmed`. |
| `timestamp` | När ändringen skedde, som en ISO 8601 UTC-tidpunkt. Inte tidpunkten för utskicket. |
| `data` | Det ändrade objektet. Strukturen beror på händelsetypen. |

### Data för statushändelser

| Fält | Beskrivning |
| - | - |
| `object` | `appointment` eller `home_kit_order`. |
| `id` | Id (UUID) för bokningen eller beställningen av hemtestkit. |
| `url` | `/api/v1/appointments/{id}` eller `/api/v1/home-kit-orders/{id}`. |
| `status` | Status efter ändringen. |
| `previous_status` | Status före ändringen. `null` vid `created`. |
| `status_revision` | Räknare per objekt. Den ökar vid varje statusändring och kan hoppa över nummer. |

```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 för resultathändelser

| Fält | Beskrivning |
| - | - |
| `object` | `appointment`, `home_kit_order` eller `document`. |
| `id` | Id (UUID) för bokningen, beställningen av hemtestkit eller dokumentet. |
| `url` | Objektets `/results`-sökväg, t.ex. `/api/v1/documents/{id}/results`. |
| `results_status` | `in_progress`, `completed` eller `fault`. Ett dokument kan även ha `stored`. |
| `previous_results_status` | `results_status` från föregående resultathändelse. `null` vid den första. |
| `results_revision` | Räknare per objekt. Den ökar vid varje resultatändring och kan hoppa över nummer. |

```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 för händelser om borttagna dokument

`document.deleted` innehåller `object` (`document`), `id`, `previous_results_status` och
`results_revision`. Den har ingen `url`, eftersom det inte finns något kvar att läsa.

```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 för plats-, profil- och försändelsehändelser

| Fält | Beskrivning |
| - | - |
| `object` | `location`, `profile` eller `shipment`. |
| `id` | Id (UUID) för platsen eller profilen, eller försändelsens referens. |
| `url` | `/api/v1/locations/{id}`, `/api/v1/locations/{id}/retail-prices`, `/api/v1/profiles/{id}` eller `/api/v1/shipments/{id}`. Saknas vid `.deactivated` och `.deleted`. |
| `status` | Endast försändelser. Status efter ändringen. |
| `previous_status` | Endast försändelser. Status före ändringen. `null` vid `shipment.created`. |
| `revision` | Räknare per objekt över alla dess händelser. Den kan hoppa över nummer. Händelser för försäljningspriser har en egen räknare. |

```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` innehåller `data.object` `webhook` och `data.id`, webhookens id.

## Verifiera signaturen

Händelser innehåller ingen data, men du bör ändå verifiera varje händelse. En giltig signatur bevisar att
händelsen kommer från Aniva. Varje förfrågan innehåller headrarna `webhook-id`, `webhook-timestamp` (Unix-sekunder)
och `webhook-signature`.

1. Ta förfrågans råa body. Verifiera den innan du tolkar JSON.
2. Skapa det signerade innehållet `{webhook-id}.{webhook-timestamp}.{raw body}`.
3. Base64-avkoda den del av din hemlighet som kommer efter `whsec_`. Använd den som nyckel.
4. Beräkna HMAC-SHA256 för det signerade innehållet och koda det som base64.
5. Jämför det i konstant tid med varje `v1,<signature>`-post i `webhook-signature`. Posterna
   separeras med mellanslag. En träff räcker.
6. Avvisa förfrågan när `webhook-timestamp` skiljer sig mer än 5 minuter från din klocka.

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

Specifikationen är [Standard Webhooks](https://www.standardwebhooks.com). Bibliotek för Standard Webhooks
finns för de flesta språk och gör detta i ett anrop.

### Rotera hemligheten

Anropa [Rotera hemlighet](https://docs.anivahealth.com/sv/api/webhooks/rotate-secret.md) för att få en ny hemlighet. I 24 timmar
signerar Aniva med både den gamla och den nya hemligheten, så driftsätt den nya inom den tiden. Efter en läcka skickar du
`revoke_current_secret_now: true` för att stoppa den gamla hemligheten direkt.

## Leverans

* Svara med `2xx` inom 15 sekunder. Lagra eller köa händelsen och gör arbetet senare.
* Använd en `https`-URL på port 443 med en publik värd. Aniva följer inte omdirigeringar: `3xx`
  räknas som ett fel.
* Leveransen sker minst en gång och utan garanterad ordning. Filtrera bort dubbletter med `webhook-id`. Använd revisionerna för att
  ignorera en äldre händelse.
* Svara med `410 Gone` för att stoppa händelserna. Aniva inaktiverar webhooken direkt.
* Aniva sparar leveranser i 30 dagar. Efter det kan du inte lista eller skicka dem igen.

### Omförsök

Ett annat svar än `2xx`, en timeout eller ett nätverksfel startar ett omförsök. Varje händelse får upp till 10 försök
under ungefär tre dagar:

| Försök | Tid efter det första försöket |
| - | - |
| 2 | cirka 5 sekunder |
| 3 | cirka 5 minuter |
| 4 | cirka 35 minuter |
| 5 | cirka 2,5 timmar |
| 6 | cirka 7,5 timmar |
| 7 | cirka 17,5 timmar |
| 8 | cirka 27,5 timmar |
| 9 | cirka 51,5 timmar |
| 10 | cirka 75,5 timmar |

Efter försök 10 är leveransen `failed`. Skicka den igen med
[Skicka leverans igen](https://docs.anivahealth.com/sv/api/webhooks/resend-delivery.md). Den behåller samma `webhook-id`.

### Felaviseringar

Aniva mejlar webhookens `alert_emails` när ingen leverans har lyckats på 24 timmar, när en händelse är
`failed` och när webhooken inaktiveras. Efter 5 dagar utan en lyckad leverans inaktiverar Aniva
webhooken. En inaktiverad webhook får inga nya händelser, och dess väntande leveranser
avbryts.

| `disabled_reason` | Orsak |
| - | - |
| `Disabled by the partner` | Du skickade `status: "disabled"`. |
| `Disabled by Aniva` | Aniva inaktiverade webhooken. Bara Aniva kan aktivera den igen. |
| `The endpoint answered 410 Gone` | Din slutpunkt svarade `410 Gone`. |
| `No successful delivery for 5 days` | Ingen leverans lyckades på 5 dagar. |

För att starta igen åtgärdar du din slutpunkt och skickar `status: "enabled"` med
[Uppdatera webhook](https://docs.anivahealth.com/sv/api/webhooks/update-webhook.md). Missade händelser skickas inte
igen av sig själva. Skicka dem igen, eller läs det aktuella tillståndet med `GET`-slutpunkterna.

## Upprepade läsningar

Aniva lagrar svaret från vissa `GET`-slutpunkter under en kort tid. När din API-nyckel skickar samma
begäran igen inom den tiden får du det lagrade svaret. Du får inget fel, och svarskroppen har
samma format.

* **En post** (en försändelse, en beställning av hemtestkit, en bokning och resultaten för de två sista):
  vid varje anrop kontrollerar Aniva att posten är oförändrad. Om den har ändrats får du ett färskt svar.
* **En lista** kan vara äldre än sina poster, högst 5 minuter.

För att få veta om en ändring direkt använder du webhook-händelserna i tabellen.

| Slutpunkt | Lagras i | Händelser som meddelar dig om en ändring |
| - | - | - |
| [Hämta försändelse](https://docs.anivahealth.com/sv/api/shipments/get-shipment.md) | 60 minuter | `shipment.created`, `shipment.updated` |
| [Lista försändelser](https://docs.anivahealth.com/sv/api/shipments/list-shipments.md) | 5 minuter | `shipment.created`, `shipment.updated` |
| [Hämta beställning av hemtestkit](https://docs.anivahealth.com/sv/api/home-kit-orders/get-home-kit.md) | 60 minuter | `home_kit_order.created` och en händelse per status, till exempel `home_kit_order.activated` |
| [Hämta resultat för beställning av hemtestkit](https://docs.anivahealth.com/sv/api/home-kit-orders/get-results.md) | 60 minuter | `home_kit_order.results.updated`, `.completed`, `.fault` |
| [Lista beställningar av hemtestkit](https://docs.anivahealth.com/sv/api/home-kit-orders/list-home-kits.md) | 5 minuter | samma händelser som för en beställning av hemtestkit |
| [Hämta bokning](https://docs.anivahealth.com/sv/api/appointments/get-appointment.md) | 15 minuter | `appointment.created`, `appointment.rescheduled` och en händelse per status, till exempel `appointment.confirmed` |
| [Hämta resultat för bokning](https://docs.anivahealth.com/sv/api/appointments/get-results.md) | 60 minuter | `appointment.results.updated`, `.completed`, `.fault` |
| [Lista bokningar](https://docs.anivahealth.com/sv/api/appointments/list-appointments.md) | 5 minuter | samma händelser som för en bokning |
| [Lista profiler](https://docs.anivahealth.com/sv/api/profiles/list-profiles.md) | 5 minuter | `profile.created`, `profile.updated`, `profile.deleted` |

* Samma begäran innebär samma API-nyckel, samma slutpunkt och samma frågeparametrar. En annan
  sida i en lista är en annan begäran och får ett eget svar.
* Aniva lagrar bara `200`-svar. Ett fel lagras aldrig.
* Tiden börjar när Aniva lagrar svaret. Ett senare anrop förlänger den inte.
* När din API-nyckel har skapat, uppdaterat, aktiverat eller avbrutit något blir din nästa läsning färsk.
  Nästa läsning av den posten med en annan av dina API-nycklar blir också färsk.
* I ett lagrat försändelsesvar kan fälten `synced_at` och `updated_at` vara äldre än i ett
  färskt svar. Status, spårning och adresser är aktuella.
* I ett lagrat resultatsvar kan ett biomarkörnamn, en enhet eller ett konverterat värde vara upp till 60
  minuter gammalt efter att Aniva ändrat sin katalog. De uppmätta värdena är aktuella.
* När Aniva skapar en webhook-händelse för din webhook blir nästa läsning av den posten, av dess
  resultat och av dess listor färsk. Läsningen som följer efter en händelse visar därför alltid ändringen.

### Svarsheaders

Varje svar från dessa slutpunkter till en giltig API-nyckel har dessa headers:

| Header | Skickas med | Betydelse |
| - | - | - |
| `Aniva-Webhook-Events` | Varje svar | De webhook-händelser som omfattar slutpunkten, separerade med kommatecken. |
| `Link` | Varje svar | Adressen till den här sidan, med `rel="help"`. |
| `Cache-Status` | Ett `200`-svar | `Aniva; hit; ttl=3476` är ett lagrat svar. `ttl` är antalet sekunder tills ett färskt svar finns tillgängligt. `Aniva; fwd=miss; stored; ttl=3600` är ett färskt svar som Aniva lagrade nu. `Aniva; fwd=miss` är ett färskt svar som Aniva inte lagrade. |
| `Age` | Ett lagrat svar | Det lagrade svarets ålder i sekunder. |
| `Cache-Control` | Ett `200`-svar | `private, no-cache`. Spara inte svaret i en egen cache i stället för att anropa 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"
```

## Bästa praxis

* **Filtrera bort dubbletter.** Hoppa över en händelse vars `webhook-id` du redan har bearbetat.
* **Använd revisionerna.** Lagra högsta `status_revision`, `results_revision` och `revision`
  per objekt. Ignorera en händelse med ett lägre värde.
* **Hämta `url`.** Händelsen talar om att något har ändrats. `GET`-slutpunkten talar om vad.
* **Svara snabbt.** Köa händelsen och svara med `2xx` innan du bearbetar den.
* **Stäm av.** Kör ett regelbundet jobb som läser öppna objekt med `GET`-slutpunkterna. Polling är fortfarande en
  giltig reservlösning. En upprepad läsning kan ge ett lagrat svar, se [Upprepade läsningar](#upprepade-laesningar).
* **Testa efter varje driftsättning.** Använd [Skicka testhändelse](https://docs.anivahealth.com/sv/api/webhooks/send-test-event.md).


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