POST pieprasījums, ko Aniva nosūta uz tavu serveri, kad kaut kas mainās. Tev nav
jāveic aptaujāšana.
Notikumi ir kompakti. Tie satur objekta ID, jauno statusu, revīziju un nolasāmo url. Tie
nekad nesatur laboratorijas rādītājus vai personas datus. Nolasi url ar savu API atslēgu, lai iegūtu datus.
Ātrā iestatīšana
- Izveido HTTPS galapunktu, kas pieņem
POSTun atbild ar2xx15 sekunžu laikā. - Reģistrē to, izmantojot Izveidot tīmekļa āķi.
Saglabā
secretno atbildes. Aniva to parāda tikai vienu reizi. - Pārbaudi parakstu katram pieprasījumam.
- Nosūti testa notikumu. Pārbaudi rezultātu Piegāžu sarakstā.
webhooks_manage tvērums. Palūdz Aniva to pievienot. Tīmekļa āķis pieder
API atslēgai, kas to izveidoja, un vienai atslēgai var piederēt ne vairāk kā 5 tīmekļa āķi.
Notikumi
Tu saņem notikumu tikai par objektiem, kurus tava API atslēga var lasīt ar atbilstošoGET galapunktu.
Izvēlies veidus ar enabled_events. Nosūti ["*"], lai saņemtu visus veidus, arī vēlāk pievienotos.
- Statusa notikums nostrādā katrā pārejā uz šo statusu, arī pārejot atpakaļ. Piemēram, komplekts,
kas no
dispatchedatgriežas uzpending, nosūtahome_kit_order.pending. - Viena izmaiņa var nosūtīt divus notikumus ar vienādu
status_revision, piemēram,appointment.confirmedunappointment.rescheduled. results.updatednostrādā pie katras rezultātu izmaiņas: jaunas vērtības, labojuma, kļūdas, jauna vai aizstāta dokumenta vai parauga, kas tiek izņemts no objekta. Tas pienāk dažu minūšu laikā pēc pēdējās izmaiņas.results.completedunresults.faultvienmēr pienāk kopā arresults.updated, kam ir tāds patsresults_revision. Rezultātus var atvērt atkārtoti un pabeigt vēlreiz, tāpēc tu vari saņemt otruresults.completed.
results.updated, lai rādītu daļējus rezultātus, vai results.completed, lai rīkotos tikai pēc
gala rezultātiem.
results.completed seko rezultātu vērtībām, nevis PDF failam. Pārskata PDF var pienākt pirms vai
pēc vērtībām. Dažas laboratorijas vispirms nosūta provizorisku PDF un vēlāk to aizstāj ar galīgo
ar to pašu dokumenta id. Aizstāšana nosūta results.updated. Lasi
documents[].original_file_name, lai abus atšķirtu: Labor Quade provizoriskajam pārskatam
(Vorbefund) beigās liek _V, bet galīgajam pārskatam (Endbefund) — _E, piemēram,
7642100312_B0012_FA_E.pdf.
Atrašanās vietu, profilu un sūtījumu notikumi pienāk dažu minūšu laikā. Aniva gaida, līdz objekts
nav mainījies 2 minūtes, tāpēc vairāki labojumi pēc kārtas nosūta vienu notikumu. Spēkā ir arī šie noteikumi:
- Anonīmi profili nesūta notikumus.
- Sūtījums nesūta notikumu, kad tu zaudē piekļuvi tam.
- Sūtījuma statusa izmaiņa nosūta
shipment.updatedunshipment.<status>notikumu ar vienādurevision.
Saturs
Statusa notikuma dati
appointment.confirmed
Rezultātu notikuma dati
home_kit_order.results.completed
Dokumenta dzēšanas notikuma dati
document.deleted satur object (document), id, previous_results_status un
results_revision. Tam nav url, jo vairs nav nekā, ko lasīt.
document.deleted
Atrašanās vietas, profila un sūtījuma notikuma dati
shipment.in_transit
ping satur data.object webhook un data.id — webhook ID.
Paraksta pārbaude
Notikumi nesatur datus, bet tev tik un tā vajadzētu pārbaudīt katru no tiem. Derīgs paraksts pierāda, ka notikums nācis no Aniva. Katrs pieprasījums satur galveneswebhook-id, webhook-timestamp (Unix
sekundes) un webhook-signature.
- Paņem neapstrādāto pieprasījuma pamattekstu. Pārbaudi to, pirms analizē JSON.
- Izveido parakstīto saturu
{webhook-id}.{webhook-timestamp}.{raw body}. - Dekodē ar base64 sava noslēpuma daļu aiz
whsec_. Izmanto to kā atslēgu. - Aprēķini parakstītā satura HMAC-SHA256 un kodē to base64 formātā.
- Konstantā laikā salīdzini to ar katru
v1,<signature>ierakstu nowebhook-signature. Ieraksti ir atdalīti ar atstarpēm. Pietiek ar vienu sakritību. - Noraidi pieprasījumu, ja
webhook-timestampatšķiras no tava pulksteņa par vairāk nekā 5 minūtēm.
Node.js
Noslēpuma rotācija
Izsauc Nomainīt slepeno atslēgu, lai iegūtu jaunu slepeno atslēgu. 24 stundas Aniva paraksta ar veco un jauno slepeno atslēgu, tāpēc šajā laikā ievies jauno. Pēc noplūdes nosūtirevoke_current_secret_now: true, lai uzreiz apturētu veco slepeno atslēgu.
Piegāde
- Atbildi ar
2xx15 sekunžu laikā. Saglabā notikumu vai ievieto to rindā un apstrādā vēlāk. - Izmanto
httpsURL 443. portā ar publisku resursdatoru. Aniva neseko pāradresācijām:3xxtiek uzskatīts par kļūmi. - Piegāde notiek vismaz vienu reizi un bez noteiktas secības. Atmet dublikātus pēc
webhook-id. Izmanto revīzijas, lai ignorētu vecāku notikumu. - Atbildi ar
410 Gone, lai apturētu notikumus. Aniva uzreiz atspējo tīmekļa āķi. - Aniva glabā piegādes 30 dienas. Pēc tam tās nevar iegūt sarakstā vai nosūtīt atkārtoti.
Atkārtoti mēģinājumi
Noildze, tīkla kļūda vai atbilde, kas nav2xx, sāk atkārtotu mēģinājumu. Katram notikumam ir līdz 10 mēģinājumiem
aptuveni trīs dienu laikā:
Pēc 10. mēģinājuma piegāde ir
failed. Nosūti to vēlreiz ar
Atkārtoti nosūtīt piegādi. Tai saglabājas tas pats webhook-id.
Paziņojumi par kļūmēm
Aniva nosūta e-pastu uz tīmekļa āķaalert_emails, kad 24 stundas neviena piegāde nav izdevusies, kad notikums ir
failed un kad tīmekļa āķis tiek atspējots. Pēc 5 dienām bez veiksmīgas piegādes Aniva
atspējo tīmekļa āķi. Atspējots tīmekļa āķis nesaņem jaunus notikumus, un tā gaidīšanā esošās piegādes tiek
atceltas.
Lai atsāktu, salabo savu galapunktu un nosūti
status: "enabled" ar
Atjaunināt tīmekļa āķi. Nesaņemtie notikumi netiek nosūtīti
vēlreiz paši no sevis. Nosūti tos atkārtoti vai nolasi pašreizējo stāvokli ar GET galapunktiem.
Atkārtota nolasīšana
Aniva īsu laiku glabā dažuGET galapunktu atbildes. Kad tava API atslēga šajā laikā vēlreiz nosūta
to pašu pieprasījumu, tu saņem saglabāto atbildi. Tu nesaņem kļūdu, un saturam ir
tāds pats formāts.
- Viens ieraksts (sūtījums, mājas testa komplekta pasūtījums, pieraksts un pēdējo divu rezultāti): katrā izsaukumā Aniva pārbauda, vai ieraksts nav mainījies. Ja tas ir mainījies, tu saņem jaunu atbildi.
- Saraksts var būt vecāks par tā ierakstiem, bet ne vairāk kā par 5 minūtēm.
- Tas pats pieprasījums nozīmē to pašu API atslēgu, to pašu galapunktu un tos pašus vaicājuma parametrus. Cita saraksta lapa ir cits pieprasījums un saņem savu atbildi.
- Aniva glabā tikai
200atbildi. Kļūda nekad netiek saglabāta. - Laiks sākas brīdī, kad Aniva saglabā atbildi. Vēlāks izsaukums to nepagarina.
- Kad tava API atslēga kaut ko izveido, atjaunina, aktivizē vai atceļ, tava nākamā nolasīšana atgriež jaunu atbildi. Arī nākamā šī ieraksta nolasīšana ar citu tavu API atslēgu atgriež jaunu atbildi.
- Saglabātā sūtījuma atbildē lauki
synced_atunupdated_atvar būt vecāki nekā jaunā atbildē. Statuss, izsekošana un adreses ir aktuālas. - Saglabātā rezultātu atbildē biomarķiera nosaukums, mērvienība vai pārrēķinātā vērtība var būt līdz 60 minūtēm veci pēc tam, kad Aniva maina savu katalogu. Izmērītās vērtības ir aktuālas.
- Kad Aniva izveido tīmekļa āķa notikumu tavam tīmekļa āķim, tava nākamā šī ieraksta, tā rezultātu un sarakstu nolasīšana atgriež jaunu atbildi. Tādējādi nolasīšana pēc notikuma vienmēr parāda izmaiņas.
Atbildes galvenes
Katrā šo galapunktu atbildē derīgai API atslēgai ir šādas galvenes:Labākā prakse
- Atmet dublikātus. Izlaid notikumu, kura
webhook-idjau esi apstrādājis. - Izmanto revīzijas. Saglabā augstāko
status_revision,results_revisionunrevisionkatram objektam. Ignorē notikumu ar zemāku vērtību. - Iegūsti
url. Notikums paziņo, ka kaut kas ir mainījies.GETgalapunkts parāda, kas tieši. - Atbildi ātri. Ievieto notikumu rindā un atbildi ar
2xx, pirms to apstrādā. - Saskaņo datus. Regulāri palaid uzdevumu, kas nolasa atvērtos objektus ar
GETgalapunktiem. Aptaujāšana joprojām ir derīgs rezerves risinājums. Atkārtota nolasīšana var atgriezt saglabātu atbildi, skatīt Atkārtota nolasīšana. - Pārbaudi pēc katras ieviešanas. Izmanto Nosūtīt testa notikumu.