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
- Zbuduj punkt końcowy HTTPS, który przyjmuje
POSTi odpowiada kodem2xxw ciągu 15 sekund. - Zarejestruj go za pomocą Utwórz webhook.
Zapisz
secretz odpowiedzi. Aniva wyświetla go tylko raz. - Zweryfikuj podpis każdego żądania.
- Wyślij zdarzenie testowe. Sprawdź wynik w Liście dostarczeń.
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 endpointuGET.
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
dispatcheddopending, wysyłahome_kit_order.pending. - Jedna zmiana może wysłać dwa zdarzenia z tym samym
status_revision, na przykładappointment.confirmediappointment.rescheduled. results.updatedjest 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.completediresults.faultzawsze przychodzą razem zresults.updatedo tym samymresults_revision. Wyniki mogą zostać ponownie otwarte i znów ukończone, więc możesz otrzymać drugieresults.completed.
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.updatedoraz zdarzenieshipment.<status>z tym samymrevision.
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
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łówkiwebhook-id, webhook-timestamp (sekundy
Unix) oraz webhook-signature.
- Weź surową treść żądania. Zweryfikuj ją, zanim sparsujesz JSON.
- Zbuduj podpisywaną treść
{webhook-id}.{webhook-timestamp}.{raw body}. - Zdekoduj z formatu base64 część swojego sekretu po
whsec_. Użyj jej jako klucza. - Oblicz HMAC-SHA256 z podpisywanej treści i zakoduj wynik w base64.
- Porównaj go w stałym czasie z każdym wpisem
v1,<signature>wwebhook-signature. Wpisy są rozdzielone spacjami. Wystarczy jedno dopasowanie. - Odrzuć żądanie, gdy
webhook-timestampróżni się od twojego zegara o więcej niż 5 minut.
Node.js
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ślijrevoke_current_secret_now: true, aby natychmiast unieważnić stary sekret.
Dostarczanie
- Odpowiedz
2xxw ciągu 15 sekund. Zapisz lub zakolejkuj zdarzenie i przetwórz je później. - Użyj adresu URL
httpsna porcie 443 z publicznym hostem. Aniva nie podąża za przekierowaniami:3xxliczy 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 zalert_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ówGET 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.
- 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_atiupdated_atmogą 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-idjuż przetworzono. - Używaj rewizji. Przechowuj najwyższe
status_revision,results_revisionirevisiondla każdego obiektu. Ignoruj zdarzenie z niższą wartością. - Pobieraj
url. Zdarzenie informuje, że coś się zmieniło. EndpointGETmó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.