Pāriet uz galveno saturu
Tīmekļa āķis ir HTTPS 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

  1. Izveido HTTPS galapunktu, kas pieņem POST un atbild ar 2xx 15 sekunžu laikā.
  2. Reģistrē to, izmantojot Izveidot tīmekļa āķi. Saglabā secret no atbildes. Aniva to parāda tikai vienu reizi.
  3. Pārbaudi parakstu katram pieprasījumam.
  4. Nosūti testa notikumu. Pārbaudi rezultātu Piegāžu sarakstā.
Tavai API atslēgai ir nepieciešams 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šo GET 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 dispatched atgriežas uz pending, nosūta home_kit_order.pending.
  • Viena izmaiņa var nosūtīt divus notikumus ar vienādu status_revision, piemēram, appointment.confirmed un appointment.rescheduled.
  • results.updated nostrā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.completed un results.fault vienmēr pienāk kopā ar results.updated, kam ir tāds pats results_revision. Rezultātus var atvērt atkārtoti un pabeigt vēlreiz, tāpēc tu vari saņemt otru results.completed.
Abonē 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.updated un shipment.<status> notikumu ar vienādu revision.

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 galvenes webhook-id, webhook-timestamp (Unix sekundes) un webhook-signature.
  1. Paņem neapstrādāto pieprasījuma pamattekstu. Pārbaudi to, pirms analizē JSON.
  2. Izveido parakstīto saturu {webhook-id}.{webhook-timestamp}.{raw body}.
  3. Dekodē ar base64 sava noslēpuma daļu aiz whsec_. Izmanto to kā atslēgu.
  4. Aprēķini parakstītā satura HMAC-SHA256 un kodē to base64 formātā.
  5. Konstantā laikā salīdzini to ar katru v1,<signature> ierakstu no webhook-signature. Ieraksti ir atdalīti ar atstarpēm. Pietiek ar vienu sakritību.
  6. Noraidi pieprasījumu, ja webhook-timestamp atšķiras no tava pulksteņa par vairāk nekā 5 minūtēm.
Node.js
Shēma ir Standard Webhooks. Lielākajai daļai valodu ir pieejamas Standard Webhooks bibliotēkas, kas to paveic vienā izsaukumā.

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ūti revoke_current_secret_now: true, lai uzreiz apturētu veco slepeno atslēgu.

Piegāde

  • Atbildi ar 2xx 15 sekunžu laikā. Saglabā notikumu vai ievieto to rindā un apstrādā vēlāk.
  • Izmanto https URL 443. portā ar publisku resursdatoru. Aniva neseko pāradresācijām: 3xx tiek 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 nav 2xx, 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 āķa alert_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žu GET 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.
Lai par izmaiņām uzzinātu uzreiz, izmanto tabulā norādītos tīmekļa āķa notikumus.
  • 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 200 atbildi. 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_at un updated_at var 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-id jau esi apstrādājis.
  • Izmanto revīzijas. Saglabā augstāko status_revision, results_revision un revision katram objektam. Ignorē notikumu ar zemāku vērtību.
  • Iegūsti url. Notikums paziņo, ka kaut kas ir mainījies. GET galapunkts 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 GET galapunktiem. 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.