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

> Ontvang een HTTPS-aanroep van Aniva wanneer een afspraak, een bestelling van een thuistestkit, de resultaten ervan, een geüpload document, een locatie, een profiel of een zending verandert

Een webhook is een HTTPS `POST` die Aniva naar jouw server stuurt wanneer er iets verandert. Je hoeft
niet te pollen.

Gebeurtenissen zijn licht. Ze bevatten het object-ID, de nieuwe status, een revisie en de `url` om uit te lezen. Ze
bevatten nooit labwaarden of persoonsgegevens. Lees de `url` uit met je API-sleutel om de gegevens op te halen.

## Snel instellen

1. Bouw een HTTPS-endpoint dat `POST` accepteert en binnen 15 seconden met `2xx` antwoordt.
2. Registreer het met [Webhook aanmaken](https://docs.anivahealth.com/nl/api/webhooks/create-webhook.md).
   Sla het `secret` uit de response op. Aniva toont dit maar één keer.
3. [Verifieer de handtekening](#de-handtekening-verifieren) van elk verzoek.
4. Verstuur een [testgebeurtenis](https://docs.anivahealth.com/nl/api/webhooks/send-test-event.md). Controleer het resultaat in
   [Leveringen weergeven](https://docs.anivahealth.com/nl/api/webhooks/list-deliveries.md).

Je API-sleutel heeft de scope `webhooks_manage` nodig. Vraag Aniva om deze toe te voegen. Een webhook hoort bij de
API-sleutel waarmee deze is aangemaakt, en een sleutel kan maximaal 5 webhooks hebben.

## Events

Je ontvangt alleen een event voor objecten die je API-key kan lezen met het bijbehorende `GET`-endpoint.
Kies de types met `enabled_events`. Stuur `["*"]` om elk type te ontvangen, ook types die later worden toegevoegd.

| Type | Wanneer het wordt verstuurd |
| - | - |
| `appointment.created` | De afspraak wordt zichtbaar voor jou. Eenmaal per afspraak verstuurd. |
| `appointment.pending` | De afspraak gaat naar `pending`. |
| `appointment.confirmed` | De afspraak gaat naar `confirmed`. |
| `appointment.blood_drawn` | De afspraak gaat naar `blood_drawn`. |
| `appointment.cancelled` | De afspraak gaat naar `cancelled`. |
| `appointment.rescheduled` | `scheduled_at` of de locatie verandert. Niet verstuurd wanneer de afspraak `cancelled` is. |
| `appointment.results.updated` | De resultaten veranderen. |
| `appointment.results.completed` | De `status` van de resultaten gaat naar `completed`. |
| `appointment.results.fault` | De `status` van de resultaten gaat naar `fault`. |
| `home_kit_order.created` | De bestelling wordt aangemaakt. Eenmaal per bestelling verstuurd. |
| `home_kit_order.pending` | De bestelling gaat naar `pending`. |
| `home_kit_order.dispatched` | De bestelling gaat naar `dispatched`. |
| `home_kit_order.activated` | De bestelling gaat naar `activated`. |
| `home_kit_order.cancelled` | De bestelling gaat naar `cancelled`. |
| `home_kit_order.results.updated` | De resultaten veranderen. |
| `home_kit_order.results.completed` | De `status` van de resultaten gaat naar `completed`. |
| `home_kit_order.results.fault` | De `status` van de resultaten gaat naar `fault`. |
| `document.results.updated` | De resultaten van een document dat je hebt geüpload veranderen, of het wordt opgeslagen. `stored` is definitief: er volgt geen `document.results.completed`. |
| `document.results.completed` | De `status` van de resultaten van een document dat je hebt geüpload gaat naar `completed`. |
| `document.results.fault` | De `status` van de resultaten van een document dat je hebt geüpload gaat naar `fault`. |
| `document.deleted` | Een document dat je hebt geüpload wordt verwijderd. Verstuurd naar de endpoints die het laatste resultatenevent ervan hebben ontvangen. Geen `url`. |
| `location.created` | De locatie wordt zichtbaar voor jou: nieuw, geactiveerd of toegevoegd aan een groep die je leest. |
| `location.updated` | Een veld van de locatie verandert: naam, adres, website, openingstijden, afbeelding. |
| `location.deactivated` | Je kunt de locatie niet meer lezen. |
| `location.retail_prices.updated` | Een gepubliceerde prijs voor een panel of biomarker op de locatie verandert. Vereist de scope `retail_prices_view`. |
| `profile.created` | Het profiel wordt zichtbaar voor jou: nieuw of toegevoegd aan een profielgroep die je leest. |
| `profile.updated` | Een veld van [Get Profile](https://docs.anivahealth.com/nl/api/profiles/get-profile.md) verandert. |
| `profile.deleted` | Het profiel wordt verwijderd, of je kunt het niet meer lezen. |
| `shipment.created` | De zending wordt zichtbaar voor jou. |
| `shipment.updated` | Een veld van de zending verandert: tracking, scans, ophalen, notities, links. |
| `shipment.pending` | De zending gaat naar `pending`. |
| `shipment.in_transit` | De zending gaat naar `in_transit`. |
| `shipment.delivered` | De zending gaat naar `delivered`. |
| `shipment.fault` | De zending gaat naar `fault`. |
| `shipment.cancelled` | De zending gaat naar `cancelled`. |
| `ping` | Je hebt een testevent verstuurd. Altijd verstuurd, geen onderdeel van `enabled_events`. |

* Een statusevent wordt verstuurd bij elke overgang naar die status, ook bij een stap terug. Een kit die
  bijvoorbeeld van `dispatched` teruggaat naar `pending`, verstuurt `home_kit_order.pending`.
* Eén wijziging kan twee events met dezelfde `status_revision` versturen, bijvoorbeeld
  `appointment.confirmed` en `appointment.rescheduled`.
* `results.updated` wordt verstuurd bij elke wijziging van de resultaten: een nieuwe waarde, een correctie, een fout, een nieuw
  of vervangen document, of een monster dat het object verlaat. Het komt binnen enkele minuten na de
  laatste wijziging aan.
* `results.completed` en `results.fault` komen altijd samen met een `results.updated` met dezelfde
  `results_revision`. Resultaten kunnen opnieuw worden geopend en opnieuw worden afgerond, dus je kunt een tweede
  `results.completed` krijgen.

Abonneer je op `results.updated` om gedeeltelijke resultaten te tonen, of op `results.completed` om alleen op
definitieve resultaten te reageren.

`results.completed` volgt de resultaatwaarden, niet de pdf. De rapport-pdf kan voor of
na de waarden aankomen. Sommige labs sturen eerst een voorlopige pdf en vervangen deze later door de definitieve
onder hetzelfde document-`id`. De vervanging verstuurt `results.updated`. Lees
`documents[].original_file_name` om de twee uit elkaar te houden: Labor Quade eindigt een voorlopig rapport
(Vorbefund) op `_V` en het definitieve rapport (Endbefund) op `_E`, bijvoorbeeld
`7642100312_B0012_FA_E.pdf`.

Locatie-, profiel- en zendingsevents komen binnen enkele minuten aan. Aniva wacht tot het object
2 minuten niet is veranderd, zodat een reeks wijzigingen één event verstuurt. Deze regels gelden ook:

* Anonieme profielen versturen geen events.
* Een zending verstuurt geen event wanneer je de toegang ertoe verliest.
* Een statuswijziging van een zending verstuurt `shipment.updated` en het `shipment.<status>`-event met dezelfde
  `revision`.

## Payload

| Veld | Beschrijving |
| - | - |
| `id` | Event-id (UUID). Gelijk aan de header `webhook-id`. Blijft hetzelfde bij opnieuw proberen en opnieuw versturen. |
| `type` | Eventtype, bijvoorbeeld `appointment.confirmed`. |
| `timestamp` | Wanneer de wijziging plaatsvond, als een ISO 8601 UTC-tijdstip. Niet het moment van verzenden. |
| `data` | Het gewijzigde object. De structuur hangt af van het eventtype. |

### Gegevens van statusevents

| Veld | Beschrijving |
| - | - |
| `object` | `appointment` of `home_kit_order`. |
| `id` | Het id van de afspraak of thuistestkitbestelling (UUID). |
| `url` | `/api/v1/appointments/{id}` of `/api/v1/home-kit-orders/{id}`. |
| `status` | De status na de wijziging. |
| `previous_status` | De status voor de wijziging. `null` bij `created`. |
| `status_revision` | Teller per object. Deze loopt bij elke statuswijziging op en kan nummers overslaan. |

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

### Gegevens van resultatenevents

| Veld | Beschrijving |
| - | - |
| `object` | `appointment`, `home_kit_order` of `document`. |
| `id` | Het id van de afspraak, thuistestkitbestelling of het document (UUID). |
| `url` | De `/results`-route van het object, bijv. `/api/v1/documents/{id}/results`. |
| `results_status` | `in_progress`, `completed` of `fault`. Een document kan ook `stored` zijn. |
| `previous_results_status` | De `results_status` van het vorige resultatenevent. `null` bij het eerste event. |
| `results_revision` | Teller per object. Deze loopt bij elke wijziging van de resultaten op en kan nummers overslaan. |

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

### Gegevens van events voor verwijderde documenten

`document.deleted` bevat `object` (`document`), `id`, `previous_results_status` en
`results_revision`. Het heeft geen `url`, omdat er niets meer te lezen is.

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

### Gegevens van locatie-, profiel- en zendingsevents

| Veld | Beschrijving |
| - | - |
| `object` | `location`, `profile` of `shipment`. |
| `id` | Het id van de locatie of het profiel (UUID), of de referentie van de zending. |
| `url` | `/api/v1/locations/{id}`, `/api/v1/locations/{id}/retail-prices`, `/api/v1/profiles/{id}` of `/api/v1/shipments/{id}`. Ontbreekt bij `.deactivated` en `.deleted`. |
| `status` | Alleen voor zendingen. De status na de wijziging. |
| `previous_status` | Alleen voor zendingen. De status voor de wijziging. `null` bij `shipment.created`. |
| `revision` | Teller per object over al zijn events. Deze kan nummers overslaan. Events voor verkoopprijzen hebben een eigen 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
  }
}
```

Een `ping` bevat `data.object` `webhook` en `data.id`, het webhook-id.

## De handtekening verifiëren

Events bevatten geen gegevens, maar je moet elk event toch verifiëren. Een geldige handtekening bewijst dat het
event van Aniva komt. Elk verzoek bevat de headers `webhook-id`, `webhook-timestamp`
(Unix-seconden) en `webhook-signature`.

1. Neem de ruwe requestbody. Verifieer deze voordat je de JSON parset.
2. Stel de ondertekende inhoud samen: `{webhook-id}.{webhook-timestamp}.{raw body}`.
3. Decodeer het deel van je secret na `whsec_` vanuit base64. Gebruik dit als sleutel.
4. Bereken de HMAC-SHA256 van de ondertekende inhoud en codeer deze als base64.
5. Vergelijk deze in constante tijd met elke `v1,<signature>`-waarde in `webhook-signature`. De waarden
   zijn gescheiden door spaties. Eén overeenkomst is genoeg.
6. Wijs het verzoek af wanneer `webhook-timestamp` meer dan 5 minuten afwijkt van je klok.

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

Het schema is [Standard Webhooks](https://www.standardwebhooks.com). Voor de meeste talen bestaan
Standard Webhooks-bibliotheken die dit in één aanroep doen.

### Het secret roteren

Roep [Secret roteren](https://docs.anivahealth.com/nl/api/webhooks/rotate-secret.md) aan om een nieuw secret te krijgen. Aniva
ondertekent 24 uur lang met het oude en het nieuwe secret, dus rol het nieuwe binnen die tijd uit. Stuur na een lek
`revoke_current_secret_now: true` om het oude secret direct te stoppen.

## Aflevering

* Antwoord binnen 15 seconden met `2xx`. Sla het event op of zet het in een wachtrij en verwerk het later.
* Gebruik een `https`-URL op poort 443 met een publieke host. Aniva volgt geen redirects: een `3xx`
  telt als mislukt.
* Aflevering gebeurt minstens één keer en niet op volgorde. Verwijder duplicaten op basis van `webhook-id`. Gebruik de revisies om
  een ouder event te negeren.
* Antwoord met `410 Gone` om de events te stoppen. Aniva schakelt de webhook direct uit.
* Aniva bewaart afleveringen 30 dagen. Daarna kun je ze niet meer opvragen of opnieuw verzenden.

### Nieuwe pogingen

Een antwoord anders dan `2xx`, een time-out of een netwerkfout start een nieuwe poging. Elk event krijgt maximaal 10 pogingen
verspreid over ongeveer drie dagen:

| Poging | Tijd na de eerste poging |
| - | - |
| 2 | ongeveer 5 seconden |
| 3 | ongeveer 5 minuten |
| 4 | ongeveer 35 minuten |
| 5 | ongeveer 2,5 uur |
| 6 | ongeveer 7,5 uur |
| 7 | ongeveer 17,5 uur |
| 8 | ongeveer 27,5 uur |
| 9 | ongeveer 51,5 uur |
| 10 | ongeveer 75,5 uur |

Na poging 10 is de aflevering `failed`. Verzend deze opnieuw met
[Aflevering opnieuw verzenden](https://docs.anivahealth.com/nl/api/webhooks/resend-delivery.md). Deze behoudt dezelfde `webhook-id`.

### Foutmeldingen

Aniva mailt de `alert_emails` van de webhook wanneer er 24 uur lang geen aflevering is geslaagd, wanneer een event
`failed` is en wanneer de webhook is uitgeschakeld. Na 5 dagen zonder geslaagde aflevering schakelt Aniva
de webhook uit. Een uitgeschakelde webhook krijgt geen nieuwe events en wachtende afleveringen worden
geannuleerd.

| `disabled_reason` | Oorzaak |
| - | - |
| `Disabled by the partner` | Je hebt `status: "disabled"` verstuurd. |
| `Disabled by Aniva` | Aniva heeft de webhook uitgeschakeld. Alleen Aniva kan hem weer inschakelen. |
| `The endpoint answered 410 Gone` | Je endpoint antwoordde met `410 Gone`. |
| `No successful delivery for 5 days` | Er is 5 dagen lang geen aflevering geslaagd. |

Om opnieuw te starten, herstel je je endpoint en stuur je `status: "enabled"` met
[Webhook bijwerken](https://docs.anivahealth.com/nl/api/webhooks/update-webhook.md). Gemiste events worden niet
vanzelf opnieuw verstuurd. Verzend ze opnieuw of lees de huidige status met de `GET`-endpoints.

## Herhaalde leesverzoeken

Aniva slaat het antwoord van sommige `GET`-endpoints korte tijd op. Wanneer je API-sleutel hetzelfde
verzoek binnen deze tijd opnieuw stuurt, krijg je het opgeslagen antwoord. Je krijgt geen foutmelding en de body heeft
hetzelfde formaat.

* **Eén record** (een zending, een thuistestkitbestelling, een afspraak en de resultaten van de laatste twee):
  bij elke aanroep controleert Aniva of het record ongewijzigd is. Is het gewijzigd, dan krijg je een nieuw antwoord.
* **Een lijst** kan ouder zijn dan de records erin, maximaal 5 minuten.

Gebruik de webhook-events in de tabel om direct op de hoogte te zijn van een wijziging.

| Endpoint | Opgeslagen voor | Events die een wijziging melden |
| - | - | - |
| [Zending ophalen](https://docs.anivahealth.com/nl/api/shipments/get-shipment.md) | 60 minuten | `shipment.created`, `shipment.updated` |
| [Zendingen weergeven](https://docs.anivahealth.com/nl/api/shipments/list-shipments.md) | 5 minuten | `shipment.created`, `shipment.updated` |
| [Thuistestkitbestelling ophalen](https://docs.anivahealth.com/nl/api/home-kit-orders/get-home-kit.md) | 60 minuten | `home_kit_order.created` en één event per status, bijvoorbeeld `home_kit_order.activated` |
| [Resultaten van thuistestkitbestelling ophalen](https://docs.anivahealth.com/nl/api/home-kit-orders/get-results.md) | 60 minuten | `home_kit_order.results.updated`, `.completed`, `.fault` |
| [Thuistestkitbestellingen weergeven](https://docs.anivahealth.com/nl/api/home-kit-orders/list-home-kits.md) | 5 minuten | dezelfde events als voor één thuistestkitbestelling |
| [Afspraak ophalen](https://docs.anivahealth.com/nl/api/appointments/get-appointment.md) | 15 minuten | `appointment.created`, `appointment.rescheduled` en één event per status, bijvoorbeeld `appointment.confirmed` |
| [Resultaten van afspraak ophalen](https://docs.anivahealth.com/nl/api/appointments/get-results.md) | 60 minuten | `appointment.results.updated`, `.completed`, `.fault` |
| [Afspraken weergeven](https://docs.anivahealth.com/nl/api/appointments/list-appointments.md) | 5 minuten | dezelfde events als voor één afspraak |
| [Profielen weergeven](https://docs.anivahealth.com/nl/api/profiles/list-profiles.md) | 5 minuten | `profile.created`, `profile.updated`, `profile.deleted` |

* Hetzelfde verzoek betekent dezelfde API-sleutel, hetzelfde endpoint en dezelfde queryparameters. Een andere
  pagina van een lijst is een ander verzoek en krijgt een eigen antwoord.
* Aniva slaat alleen een `200`-antwoord op. Een fout wordt nooit opgeslagen.
* De tijd start zodra Aniva het antwoord opslaat. Een latere aanroep verlengt die tijd niet.
* Nadat je API-sleutel iets aanmaakt, bijwerkt, activeert of annuleert, krijgt je volgende leesverzoek een nieuw antwoord.
  Het volgende leesverzoek voor dat record met een andere API-sleutel van jou krijgt ook een nieuw antwoord.
* In een opgeslagen antwoord voor een zending kunnen de velden `synced_at` en `updated_at` ouder zijn dan in een
  nieuw antwoord. Status, tracking en adressen zijn actueel.
* In een opgeslagen antwoord met resultaten kunnen de naam van een biomarker, een eenheid of een omgerekende waarde tot 60
  minuten oud zijn nadat Aniva de catalogus wijzigt. De gemeten waarden zijn actueel.
* Nadat Aniva een webhook-event voor je webhook aanmaakt, krijgt je volgende leesverzoek voor dat record, de
  resultaten ervan en de bijbehorende lijsten een nieuw antwoord. Het leesverzoek na een event toont dus altijd de wijziging.

### Response-headers

Elk antwoord van deze endpoints aan een geldige API-sleutel bevat deze headers:

| Header | Meegestuurd bij | Betekenis |
| - | - | - |
| `Aniva-Webhook-Events` | Elk antwoord | De webhook-events die bij het endpoint horen, gescheiden door komma's. |
| `Link` | Elk antwoord | Het adres van deze pagina, met `rel="help"`. |
| `Cache-Status` | Een `200`-antwoord | `Aniva; hit; ttl=3476` is een opgeslagen antwoord. `ttl` is het aantal seconden tot er een nieuw antwoord beschikbaar is. `Aniva; fwd=miss; stored; ttl=3600` is een nieuw antwoord dat Aniva nu heeft opgeslagen. `Aniva; fwd=miss` is een nieuw antwoord dat Aniva niet heeft opgeslagen. |
| `Age` | Een opgeslagen antwoord | De leeftijd van het opgeslagen antwoord in seconden. |
| `Cache-Control` | Een `200`-antwoord | `private, no-cache`. Bewaar het antwoord niet in een eigen cache in plaats van een aanroep naar 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"
```

## Best practices

* **Verwijder duplicaten.** Sla een event over waarvan je de `webhook-id` al hebt verwerkt.
* **Gebruik de revisies.** Sla de hoogste `status_revision`, `results_revision` en `revision`
  per object op. Negeer een event met een lagere waarde.
* **Haal de `url` op.** Het event geeft aan dat er iets is gewijzigd. Het `GET`-endpoint geeft aan wat.
* **Antwoord snel.** Zet het event in een wachtrij en antwoord met `2xx` voordat je het verwerkt.
* **Synchroniseer regelmatig.** Draai regelmatig een taak die openstaande objecten uitleest met de `GET`-endpoints. Polling blijft een
  geldige terugvaloptie. Een herhaald leesverzoek kan een opgeslagen antwoord terugkrijgen, zie [Herhaalde leesverzoeken](#herhaalde-leesverzoeken).
* **Test na elke deploy.** Gebruik [Testevent verzenden](https://docs.anivahealth.com/nl/api/webhooks/send-test-event.md).


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