Ana içeriğe atla
Webhook, bir şey değiştiğinde Aniva’nın sunucuna gönderdiği bir HTTPS POST isteğidir. Yoklama yapmana gerek yoktur. Olaylar hafiftir. Nesne ID’sini, yeni durumu, bir revizyonu ve okunacak url adresini taşırlar. Asla laboratuvar değerleri veya kişisel veriler taşımazlar. Verileri almak için url adresini API anahtarınla oku.

Hızlı kurulum

  1. POST kabul eden ve 15 saniye içinde 2xx yanıtı veren bir HTTPS uç noktası oluştur.
  2. Bunu Webhook oluştur ile kaydet. Yanıttaki secret değerini sakla. Aniva bunu yalnızca bir kez gösterir.
  3. Her isteğin imzasını doğrula.
  4. Bir test olayı gönder. Sonucu Teslimatları listele üzerinden kontrol et.
API anahtarının webhooks_manage kapsamına ihtiyacı vardır. Bunu eklemesini Aniva’dan iste. Bir webhook kendisini oluşturan API anahtarına aittir ve bir anahtar en fazla 5 webhook’a sahip olabilir.

Olaylar

Yalnızca API anahtarının eşleşen GET uç noktasıyla okuyabildiği nesneler için olay alırsın. Türleri enabled_events ile seç. Sonradan eklenenler dahil her türü almak için ["*"] gönder.
  • Bir durum olayı, geri dönüşler dahil o duruma her geçişte tetiklenir. Örneğin dispatched durumundan tekrar pending durumuna dönen bir kit home_kit_order.pending gönderir.
  • Tek bir değişiklik aynı status_revision ile iki olay gönderebilir; örneğin appointment.confirmed ve appointment.rescheduled.
  • results.updated, sonuçlardaki her değişiklikte tetiklenir: yeni bir değer, düzeltme, hata, yeni veya değiştirilmiş bir belge ya da nesneden ayrılan bir numune. Son değişiklikten birkaç dakika içinde ulaşır.
  • results.completed ve results.fault her zaman aynı results_revision değerine sahip bir results.updated ile birlikte gelir. Sonuçlar yeniden açılıp tekrar tamamlanabilir, bu yüzden ikinci bir results.completed alabilirsin.
Kısmi sonuçları göstermek için results.updated olayına, yalnızca kesin sonuçlara göre işlem yapmak için results.completed olayına abone ol. results.completed PDF’i değil, sonuç değerlerini takip eder. Rapor PDF’i değerlerden önce veya sonra ulaşabilir. Bazı laboratuvarlar önce bir ön rapor PDF’i gönderir ve daha sonra bunu aynı belge id değeri altında kesin raporla değiştirir. Değiştirme işlemi results.updated gönderir. İkisini ayırt etmek için documents[].original_file_name alanını oku: Labor Quade ön raporu (Vorbefund) _V ile, kesin raporu (Endbefund) _E ile bitirir; örneğin 7642100312_B0012_FA_E.pdf. Konum, profil ve gönderi olayları birkaç dakika içinde ulaşır. Aniva, nesne 2 dakika boyunca değişmeyene kadar bekler; böylece art arda yapılan düzenlemeler tek bir olay gönderir. Şu kurallar da geçerlidir:
  • Anonim profiller olay göndermez.
  • Bir gönderiye erişimini kaybettiğinde gönderi olay göndermez.
  • Bir gönderi durumu değişikliği, aynı revision değeriyle shipment.updated ve shipment.<status> olayını gönderir.

Veri yükü

Durum olayı verileri

appointment.confirmed

Sonuç olayı verileri

home_kit_order.results.completed

Belge silme olayı verileri

document.deleted, object (document), id, previous_results_status ve results_revision alanlarını taşır. Okunacak bir şey kalmadığı için url içermez.
document.deleted

Konum, profil ve gönderi olayı verileri

shipment.in_transit
ping, data.object olarak webhook ve data.id olarak webhook kimliğini taşır.

İmzayı doğrula

Olaylar veri taşımaz ama yine de her birini doğrulamalısın. Geçerli bir imza, olayın Aniva’dan geldiğini kanıtlar. Her istek webhook-id, webhook-timestamp (Unix saniyesi) ve webhook-signature başlıklarını taşır.
  1. Ham istek gövdesini al. JSON’ı ayrıştırmadan önce doğrula.
  2. İmzalanan içeriği {webhook-id}.{webhook-timestamp}.{raw body} biçiminde oluştur.
  3. Gizli anahtarının whsec_ sonrasındaki kısmını base64 ile çöz. Bunu anahtar olarak kullan.
  4. İmzalanan içeriğin HMAC-SHA256 değerini hesapla ve base64 olarak kodla.
  5. Bunu webhook-signature içindeki her v1,<signature> girdisiyle sabit zamanda karşılaştır. Girdiler boşluklarla ayrılır. Tek bir eşleşme yeterlidir.
  6. webhook-timestamp saatinden 5 dakikadan fazla farklıysa isteği reddet.
Node.js
Bu şema Standard Webhooks standardıdır. Çoğu dil için Standard Webhooks kütüphaneleri mevcuttur ve bunu tek bir çağrıda yapar.

Gizli anahtarı yenile

Yeni bir gizli anahtar almak için Gizli anahtarı döndür çağrısını yap. Aniva 24 saat boyunca hem eski hem de yeni gizli anahtarla imzalama yapar; bu yüzden yenisini bu süre içinde devreye al. Bir sızıntı sonrasında eski gizli anahtarı hemen durdurmak için revoke_current_secret_now: true gönder.

Teslimat

  • 15 saniye içinde 2xx yanıtı ver. Olayı sakla veya kuyruğa al ve işlemi daha sonra yap.
  • Herkese açık bir sunucuda 443 portunda bir https URL’si kullan. Aniva yönlendirmeleri takip etmez: 3xx yanıtı başarısız sayılır.
  • Teslimat en az bir kez ve sırasız yapılır. webhook-id değerine göre yinelenenleri atla. Daha eski bir olayı yoksaymak için revizyonları kullan.
  • Olayları durdurmak için 410 Gone yanıtı ver. Aniva webhook’u hemen devre dışı bırakır.
  • Aniva teslimatları 30 gün boyunca saklar. Bu süreden sonra bunları listeleyemez veya yeniden gönderemezsin.

Yeniden denemeler

2xx dışındaki bir yanıt, zaman aşımı veya ağ hatası yeniden denemeyi başlatır. Her olay için yaklaşık üç gün boyunca en fazla 10 deneme yapılır: Teslimat, 10. denemeden sonra failed olur. Teslimatı yeniden gönder ile tekrar gönder. Aynı webhook-id korunur.

Hata bildirimleri

24 saat boyunca hiçbir teslimat başarılı olmadığında, bir olay failed durumuna geçtiğinde ve webhook devre dışı bırakıldığında Aniva, webhook’un alert_emails adreslerine e-posta gönderir. Başarılı bir teslimat olmadan 5 gün geçtikten sonra Aniva webhook’u devre dışı bırakır. Devre dışı bırakılan bir webhook yeni olay almaz ve bekleyen teslimatları iptal edilir. Yeniden başlamak için uç noktanı düzelt ve Webhook’u güncelle ile status: "enabled" gönder. Kaçırılan olaylar kendiliğinden tekrar gönderilmez. Bunları yeniden gönder veya GET uç noktalarıyla mevcut durumu oku.

Tekrarlanan okumalar

Aniva bazı GET uç noktalarının yanıtını kısa bir süre saklar. API anahtarın bu süre içinde aynı isteği tekrar gönderdiğinde saklanan yanıtı alırsın. Hata almazsın ve gövde aynı biçimde olur.
  • Tek bir kayıt (bir gönderi, bir evde test kiti siparişi, bir randevu ve son ikisinin sonuçları): Aniva her çağrıda kaydın değişmediğini kontrol eder. Değiştiyse yeni bir yanıt alırsın.
  • Bir liste, kayıtlarından en fazla 5 dakika daha eski olabilir.
Bir değişikliği hemen öğrenmek için tablodaki webhook olaylarını kullan.
  • Aynı istek; aynı API anahtarı, aynı uç nokta ve aynı sorgu parametreleri anlamına gelir. Bir listenin başka bir sayfası farklı bir istektir ve kendi yanıtını alır.
  • Aniva yalnızca 200 yanıtını saklar. Bir hata hiçbir zaman saklanmaz.
  • Süre, Aniva yanıtı sakladığında başlar. Daha sonraki bir çağrı bu süreyi uzatmaz.
  • API anahtarın bir şey oluşturduktan, güncelledikten, etkinleştirdikten veya iptal ettikten sonra bir sonraki okuman güncel olur. Bu kaydın başka bir API anahtarınla yapılan bir sonraki okuması da güncel olur.
  • Saklanan bir gönderi yanıtında synced_at ve updated_at alanları yeni bir yanıttakinden daha eski olabilir. Durum, takip ve adresler günceldir.
  • Saklanan bir sonuç yanıtında, Aniva kataloğunu değiştirdikten sonra bir biyobelirteç adı, bir birim veya dönüştürülmüş bir değer en fazla 60 dakika eski olabilir. Ölçülen değerler günceldir.
  • Aniva webhook’un için bir webhook olayı oluşturduktan sonra o kaydın, sonuçlarının ve listelerinin bir sonraki okuması güncel olur. Dolayısıyla bir olayı izleyen okuma her zaman değişikliği gösterir.

Yanıt başlıkları

Bu uç noktaların geçerli bir API anahtarına verdiği her yanıtta şu başlıklar yer alır:

En iyi uygulamalar

  • Yinelenenleri atla. webhook-id değerini zaten işlediğin bir olayı atla.
  • Revizyonları kullan. Nesne başına en yüksek status_revision, results_revision ve revision değerlerini sakla. Daha düşük değerli bir olayı yoksay.
  • url adresini getir. Olay bir şeyin değiştiğini söyler. GET uç noktası ise neyin değiştiğini söyler.
  • Hızlı yanıt ver. Olayı kuyruğa al ve işlemeden önce 2xx yanıtı ver.
  • Eşitle. Açık nesneleri GET uç noktalarıyla okuyan düzenli bir görev çalıştır. Yoklama geçerli bir yedek yöntem olmayı sürdürür. Tekrarlanan bir okuma saklanan bir yanıt alabilir, bkz. Tekrarlanan okumalar.
  • Her dağıtımdan sonra test et. Test olayı gönder uç noktasını kullan.