Przejdź do głównej treści
Webhook to żądanie HTTPS POST, które Aniva wysyła na twój serwer, gdy coś się zmieni. Nie musisz odpytywać API. Zdarzenia są lekkie. Zawierają identyfikator obiektu, nowy status, numer wersji i adres url do odczytu. Nigdy nie zawierają wyników laboratoryjnych ani danych osobowych. Odczytaj url za pomocą swojego klucza API, aby pobrać dane.

Szybka konfiguracja

  1. Zbuduj punkt końcowy HTTPS, który przyjmuje POST i odpowiada kodem 2xx w ciągu 15 sekund.
  2. Zarejestruj go za pomocą Utwórz webhook. Zapisz secret z odpowiedzi. Aniva wyświetla go tylko raz.
  3. Zweryfikuj podpis każdego żądania.
  4. Wyślij zdarzenie testowe. Sprawdź wynik w Liście dostarczeń.
Twój klucz API wymaga zakresu webhooks_manage. Poproś Aniva o jego dodanie. Webhook należy do klucza API, który go utworzył, a jeden klucz może mieć maksymalnie 5 webhooków.

Zdarzenia

Otrzymujesz zdarzenie tylko dla obiektów, które twój klucz API może odczytać za pomocą odpowiedniego endpointu GET. Wybierz typy za pomocą enabled_events. Wyślij ["*"], aby otrzymywać każdy typ, także typy dodane później.
  • Zdarzenie statusu jest wyzwalane przy każdym przejściu w ten status, także przy powrocie. Na przykład zestaw, który wraca z dispatched do pending, wysyła home_kit_order.pending.
  • Jedna zmiana może wysłać dwa zdarzenia z tym samym status_revision, na przykład appointment.confirmed i appointment.rescheduled.
  • results.updated jest wyzwalane przy każdej zmianie wyników: nowej wartości, korekcie, błędzie, nowym lub zastąpionym dokumencie albo próbce, która opuszcza obiekt. Dociera w ciągu kilku minut od ostatniej zmiany.
  • results.completed i results.fault zawsze przychodzą razem z results.updated o tym samym results_revision. Wyniki mogą zostać ponownie otwarte i znów ukończone, więc możesz otrzymać drugie results.completed.
Zasubskrybuj results.updated, aby wyświetlać częściowe wyniki, lub results.completed, aby reagować tylko na wyniki końcowe. results.completed zależy od wartości wyników, a nie od pliku PDF. Raport PDF może dotrzeć przed wartościami lub po nich. Niektóre laboratoria najpierw wysyłają wstępny plik PDF, a później zastępują go końcowym pod tym samym id dokumentu. Zastąpienie wysyła results.updated. Odczytaj documents[].original_file_name, aby je odróżnić: Labor Quade kończy raport wstępny (Vorbefund) przyrostkiem _V, a raport końcowy (Endbefund) przyrostkiem _E, na przykład 7642100312_B0012_FA_E.pdf. Zdarzenia lokalizacji, profili i przesyłek docierają w ciągu kilku minut. Aniva czeka, aż obiekt nie zmieni się przez 2 minuty, dzięki czemu seria zmian wysyła jedno zdarzenie. Obowiązują też te zasady:
  • Anonimowe profile nie wysyłają zdarzeń.
  • Przesyłka nie wysyła zdarzenia, gdy tracisz do niej dostęp.
  • Zmiana statusu przesyłki wysyła shipment.updated oraz zdarzenie shipment.<status> z tym samym revision.

Payload

Dane zdarzenia statusu

appointment.confirmed

Dane zdarzenia wyników

home_kit_order.results.completed

Dane zdarzenia usunięcia dokumentu

document.deleted zawiera object (document), id, previous_results_status i results_revision. Nie ma pola url, ponieważ nie ma już czego odczytać.
document.deleted

Dane zdarzeń lokalizacji, profilu i przesyłki

shipment.in_transit
Zdarzenie ping zawiera data.object webhook oraz data.id, czyli identyfikator webhooka.

Zweryfikuj podpis

Zdarzenia nie zawierają danych, ale i tak weryfikuj każde z nich. Poprawny podpis potwierdza, że zdarzenie pochodzi od Aniva. Każde żądanie zawiera nagłówki webhook-id, webhook-timestamp (sekundy Unix) oraz webhook-signature.
  1. Weź surową treść żądania. Zweryfikuj ją, zanim sparsujesz JSON.
  2. Zbuduj podpisywaną treść {webhook-id}.{webhook-timestamp}.{raw body}.
  3. Zdekoduj z formatu base64 część swojego sekretu po whsec_. Użyj jej jako klucza.
  4. Oblicz HMAC-SHA256 z podpisywanej treści i zakoduj wynik w base64.
  5. Porównaj go w stałym czasie z każdym wpisem v1,<signature> w webhook-signature. Wpisy są rozdzielone spacjami. Wystarczy jedno dopasowanie.
  6. Odrzuć żądanie, gdy webhook-timestamp różni się od twojego zegara o więcej niż 5 minut.
Node.js
Schemat to Standard Webhooks. Biblioteki Standard Webhooks istnieją dla większości języków i wykonują to w jednym wywołaniu.

Wymień sekret

Wywołaj Zrotuj sekret, aby uzyskać nowy sekret. Przez 24 godziny Aniva podpisuje starym i nowym sekretem, więc wdróż nowy w tym czasie. Po wycieku wyślij revoke_current_secret_now: true, aby natychmiast unieważnić stary sekret.

Dostarczanie

  • Odpowiedz 2xx w ciągu 15 sekund. Zapisz lub zakolejkuj zdarzenie i przetwórz je później.
  • Użyj adresu URL https na porcie 443 z publicznym hostem. Aniva nie podąża za przekierowaniami: 3xx liczy się jako niepowodzenie.
  • Dostarczanie odbywa się co najmniej raz i bez zachowania kolejności. Odrzucaj duplikaty po webhook-id. Użyj rewizji, aby zignorować starsze zdarzenie.
  • Odpowiedz 410 Gone, aby zatrzymać zdarzenia. Aniva natychmiast wyłącza webhook.
  • Aniva przechowuje dostarczenia przez 30 dni. Po tym czasie nie możesz wyświetlić ich listy ani wysłać ich ponownie.

Ponowne próby

Odpowiedź inna niż 2xx, przekroczenie czasu lub błąd sieci uruchamia ponowną próbę. Każde zdarzenie ma do 10 prób w ciągu około trzech dni: Po 10. próbie dostarczenie ma status failed. Wyślij je ponownie za pomocą Ponów dostarczenie. Zachowuje ten sam webhook-id.

Powiadomienia o niepowodzeniach

Aniva wysyła e-mail na adresy z alert_emails webhooka, gdy przez 24 godziny żadne dostarczenie się nie powiedzie, gdy zdarzenie ma status failed oraz gdy webhook zostanie wyłączony. Po 5 dniach bez udanego dostarczenia Aniva wyłącza webhook. Wyłączony webhook nie otrzymuje nowych zdarzeń, a jego oczekujące dostarczenia są anulowane. Aby wznowić działanie, napraw swój endpoint i wyślij status: "enabled" za pomocą Zaktualizuj webhook. Pominięte zdarzenia nie są wysyłane ponownie automatycznie. Wyślij je ponownie albo odczytaj bieżący stan przez endpointy GET.

Powtarzane odczyty

Aniva przechowuje odpowiedź niektórych endpointów GET przez krótki czas. Gdy twój klucz API wyśle to samo żądanie ponownie w tym czasie, dostajesz zapisaną odpowiedź. Nie dostajesz błędu, a treść ma ten sam format.
  • Jeden rekord (przesyłka, zamówienie domowego zestawu testowego, wizyta oraz wyniki dwóch ostatnich): przy każdym wywołaniu Aniva sprawdza, czy rekord się nie zmienił. Jeśli się zmienił, dostajesz świeżą odpowiedź.
  • Lista może być starsza niż jej rekordy, maksymalnie o 5 minut.
Aby od razu dowiedzieć się o zmianie, użyj zdarzeń webhooka z tabeli.
  • To samo żądanie oznacza ten sam klucz API, ten sam endpoint i te same parametry zapytania. Kolejna strona listy to inne żądanie i dostaje własną odpowiedź.
  • Aniva przechowuje tylko odpowiedź 200. Błąd nigdy nie jest przechowywany.
  • Czas zaczyna biec, gdy Aniva zapisze odpowiedź. Późniejsze wywołanie go nie wydłuża.
  • Gdy twój klucz API coś utworzy, zaktualizuje, aktywuje lub anuluje, twój następny odczyt jest świeży. Następny odczyt tego rekordu z innego twojego klucza API również jest świeży.
  • W zapisanej odpowiedzi dla przesyłki pola synced_at i updated_at mogą być starsze niż w świeżej odpowiedzi. Status, śledzenie i adresy są aktualne.
  • W zapisanej odpowiedzi z wynikami nazwa biomarkera, jednostka lub przeliczona wartość mogą być starsze nawet o 60 minut po tym, jak Aniva zmieni swój katalog. Zmierzone wartości są aktualne.
  • Gdy Aniva utworzy zdarzenie webhooka dla twojego webhooka, twój następny odczyt tego rekordu, jego wyników i jego list jest świeży. Dzięki temu odczyt po zdarzeniu zawsze pokazuje zmianę.

Nagłówki odpowiedzi

Każda odpowiedź tych endpointów dla prawidłowego klucza API zawiera te nagłówki:

Dobre praktyki

  • Odrzucaj duplikaty. Pomiń zdarzenie, którego webhook-id już przetworzono.
  • Używaj rewizji. Przechowuj najwyższe status_revision, results_revision i revision dla każdego obiektu. Ignoruj zdarzenie z niższą wartością.
  • Pobieraj url. Zdarzenie informuje, że coś się zmieniło. Endpoint GET mówi co.
  • Odpowiadaj szybko. Zakolejkuj zdarzenie i odpowiedz 2xx, zanim je przetworzysz.
  • Uzgadniaj stan. Uruchamiaj regularne zadanie, które odczytuje otwarte obiekty przez endpointy GET. Odpytywanie pozostaje poprawnym rozwiązaniem zapasowym. Powtarzany odczyt może zwrócić zapisaną odpowiedź, zobacz Powtarzane odczyty.
  • Testuj po każdym wdrożeniu. Użyj Wyślij zdarzenie testowe.