Webhook abonelikleri


Google Health API, uygulamanızın kullanıcıların sağlık verileri değiştiğinde anlık bildirimler almasına olanak tanır. Sunucunuz, değişiklikleri yoklamak yerine Google Health API'de veriler kullanılabilir hale gelir gelmez bir HTTPS POST isteği (webhook) alır.

Desteklenen veri türleri

Webhook bildirimleri aşağıdaki veri türleri için desteklenir:

  • Adımlar
  • Rakım
  • Mesafe
  • Döşeme
  • Ağırlık
  • Uyku

Bu veri türleri için bildirimler yalnızca kullanıcı, ilgili kapsamların birine izin verdiğinde gönderilir:

  • Adım, yükseklik, mesafe ve kat veri türlerini kapsayan aktivite:
    • https://www.googleapis.com/auth/googlehealth.activity_and_fitness
    • https://www.googleapis.com/auth/googlehealth.activity_and_fitness.readonly
  • Kilo veri türünü kapsayan Sağlık Metrikleri:
    • https://www.googleapis.com/auth/googlehealth.health_metrics_and_measurements
    • https://www.googleapis.com/auth/googlehealth.health_metrics_and_measurements.readonly
  • Uyku veri türünü kapsayan Uyku:
    • https://www.googleapis.com/auth/googlehealth.sleep
    • https://www.googleapis.com/auth/googlehealth.sleep.readonly

Aboneleri yönetme

Bildirimleri alabilmeniz için uygulamanızın bildirim uç noktasını temsil eden bir abone kaydetmeniz gerekir. Aboneleri projects.subscribers adresindeki REST API'yi kullanarak yönetebilirsiniz.

Abone uç noktanız HTTPS (TLSv1.2+) kullanmalı ve herkese açık olmalıdır. Google Health API, abone oluşturma ve güncelleme sırasında uç nokta URI'sinin size ait olduğunu doğrulamak için doğrulama işlemi yapar. Doğrulama başarısız olursa abone oluşturma ve güncelleme işlemleri FailedPreconditionException ile başarısız olur.

Abone oluşturma

Projenize yeni bir abone kaydetmek için create uç noktasını kullanın. Şu bilgileri sağlamanız gerekir:

  • endpointUri: Webhook bildirimlerinin hedef URL'si.
  • subscriberConfigs: Bildirim almak istediğiniz veri türleri ve her biri için abonelik politikası.
  • endpointAuthorization: Uç noktanızın yetkilendirme mekanizması. Bu, sizin sağladığınız bir authorization_token içermelidir. authorization_token değeri, her bildirim iletisinde Authorization üstbilgisiyle birlikte gönderilir. Gelen isteklerin Google Health API'den geldiğini doğrulamak için bu jetonu kullanabilirsiniz. Örneğin, Taşıyıcı kimlik doğrulaması için authorization_token değerini Bearer R4nd0m5tr1ng123, Temel kimlik doğrulaması için ise Basic dXNlcjpwYXNzd29yZA== olarak ayarlayabilirsiniz.
  • subscriberId: Abone için sağladığınız benzersiz tanımlayıcı. Bu kimlik 4 ile 36 karakter arasında olmalı ve normal ifadeyle ([a-z]([a-z0-9-]{2,34}[a-z0-9])) eşleşmelidir.

subscriberConfigs içinde her veri türü için subscriptionCreatePolicy ayarlamanız gerekir. Otomatik abonelikleri kullanmak için AUTOMATIC, kullanıcı aboneliklerini kendiniz yönetmek için MANUAL olarak ayarlayın. Her seçenek hakkında daha fazla bilgi için otomatik abonelikler ve manuel abonelikler başlıklı makaleleri inceleyin.

İstek

POST https://health.googleapis.com/v4/projects/project-id/subscribers?subscriberId=subscriber-id
{
  "endpointUri": "https://myapp.com/webhooks/health",
  "subscriberConfigs": [
    {
      "dataTypes": ["steps", "altitude", "distance", "floors", "weight"],
      "subscriptionCreatePolicy": "AUTOMATIC"
    },
    {
      "dataTypes": ["sleep"],
      "subscriptionCreatePolicy": "MANUAL"
    }
  ],
  "endpointAuthorization": {
    "authorization_token": "Bearer example-secret-token"
  }
}

Yanıt

{
  "name": "projects/project-id/subscribers/subscriber-id",
  "endpointUri": "https://myapp.com/webhooks/health",
  "state": "ACTIVE",
  "subscriberConfigs": [
    {
      "dataTypes": ["steps", "altitude", "distance", "floors", "weight"],
      "subscriptionCreatePolicy": "AUTOMATIC"
    },
    {
      "dataTypes": ["sleep"],
      "subscriptionCreatePolicy": "MANUAL"
    }
  ],
  "endpointAuthorization": {
    "authorizationTokenSet": true
  }
}

Aboneleri listeleme

Projenize kayıtlı tüm aboneleri almak için list uç noktasını kullanın.

İstek

GET https://health.googleapis.com/v4/projects/project-id/subscribers

Yanıt

{
  "subscribers": [
    {
      "name": "projects/project-id/subscribers/subscriber-id",
      "endpointUri": "https://myapp.com/webhooks/health",
      "state": "ACTIVE",
      "subscriberConfigs": [
        {
          "dataTypes": ["steps", "altitude", "distance", "floors", "weight"],
          "subscriptionCreatePolicy": "AUTOMATIC"
        },
        {
          "dataTypes": ["sleep"],
          "subscriptionCreatePolicy": "MANUAL"
        }
      ],
      "endpointAuthorization": {
        "authorizationTokenSet": true
      }
    }
  ],
  "nextPageToken": ""
}

Abone güncelleme

Projenizdeki bir aboneyi güncellemek için patch uç noktasını kullanın. Güncellenebilecek alanlar şunlardır: endpointUri, subscriberConfigs ve endpointAuthorization.

Alanları, updateMask sorgu parametresi ve istek gövdesi sağlayarak güncellersiniz. updateMask, güncellemek istediğiniz alan adlarının virgülle ayrılmış bir listesini içermelidir. Alan adları için camel case kullanılmalıdır (örneğin, endpointUri). İstek gövdesi, güncellemek istediğiniz alanların yeni değerlerini içeren kısmi bir Abone nesnesi içermelidir. Yalnızca updateMask içinde belirtilen alanlar güncellenir. İstek gövdesinde updateMask'da bulunmayan alanlar sağlarsanız bu alanlar yoksayılır.

endpointUri veya endpointAuthorization güncellerseniz uç nokta doğrulaması gerçekleştirilir. Ayrıntılar için Uç nokta doğrulaması başlıklı makaleyi inceleyin.

subscriberConfigs güncellenirken bunun bir birleştirme değil, tam değiştirme olduğunu unutmayın. subscriberConfigs, updateMask içinde yer alıyorsa bu abone için depolanan tüm yapılandırmaların üzerine istek gövdesinde sağlanan liste yazılır. Yapılandırma eklemek veya kaldırmak için yapılandırmaların tamamını sağlamanız gerekir. Diğer alanları güncelliyorsanız ve mevcut yapılandırmalarınızı korumak istiyorsanız subscriberConfigs öğesini updateMask öğesinden çıkarın.

İstek

PATCH https://health.googleapis.com/v4/projects/project-id/subscribers/subscriber-id?updateMask=endpointUri
{
  "endpointUri": "https://myapp.com/new-webhooks/health"
}

Yanıt

{
  "name": "projects/project-id/subscribers/subscriber-id",
  "endpointUri": "https://myapp.com/new-webhooks/health",
  "state": "ACTIVE",
  "subscriberConfigs": [
    {
      "dataTypes": ["steps", "altitude", "distance", "floors", "weight"],
      "subscriptionCreatePolicy": "AUTOMATIC"
    },
    {
      "dataTypes": ["sleep"],
      "subscriptionCreatePolicy": "MANUAL"
    }
  ],
  "endpointAuthorization": {
    "authorizationTokenSet": true
  }
}

Uç nokta doğrulaması

Google Health API, bildirim teslimatınızın güvenliğini ve güvenilirliğini sağlamak için abone oluşturduğunuzda veya uç nokta yapılandırmasını güncellediğinizde (endpointUri veya endpointAuthorization) zorunlu iki adımlı doğrulama el sıkışması gerçekleştirir. Bu işlem, API çağrısı sırasında eşzamanlı olarak gerçekleştirilir. Hizmet, uç nokta URI'nize iki otomatik POST isteği gönderir. Bu isteklerde, JSON gövdesi {"type": "verification"} ile birlikte User-Agent Google-Health-API-Webhooks-Verifier kullanılır.

  • Yetkilendirilmiş el sıkışma: İlk istek, yapılandırılmış Authorization başlığınızla birlikte gönderilir. Sunucunuz 200 OK veya 201 Created durumuyla yanıt vermelidir.
  • Yetkisiz sorgu: İkinci istek kimlik bilgileri olmadan gönderilir. Sunucunuz 401 Unauthorized veya 403 Forbidden durumuyla yanıt vermelidir.

Bu el sıkışma, uç noktanızın etkin olduğunu ve güvenliği doğru şekilde uyguladığını onaylar. Adımlardan biri başarısız olursa API isteği FAILED_PRECONDITION hatasıyla başarısız olur. Yalnızca bu el sıkışma başarılı olduktan sonra aboneniz kaydedilir ve sağlık verileri bildirimleri alacak şekilde etkinleştirilir.

Anahtar rotasyonu

endpointAuthorization için anahtarları döndürmeniz gerekiyorsa şu adımları uygulayın:

  1. Uç noktanızı hem eski hem de yeni endpointAuthorization değerleri kabul edecek şekilde yapılandırın.
  2. endpointAuthorization değerini kullanarak abone yapılandırmasını yeni endpointAuthorization değeriyle güncelleyin ?updateMask=endpointAuthorization ile patch isteği göndererek.
  3. 2. adımın başarılı olduğunu onayladıktan sonra uç noktanızı yalnızca yeni endpointAuthorization değerini kabul edecek şekilde yapılandırın.

Abone silme

Aboneyi projenizden kaldırmak için delete uç noktasını kullanın. Silinen aboneler artık bildirim almaz.

İstek

DELETE https://health.googleapis.com/v4/projects/project-id/subscribers/subscriber-id

Yanıt

Silme işlemi başarılı olursa HTTP durumu "200 OK" olan boş bir yanıt gövdesi döndürülür. 
{}

Kullanıcı abonelikleri

Google Health API, kullanıcı aboneliklerini verimli bir şekilde yönetmenize yardımcı olarak kullanıcı oryantasyonu sırasında manuel kayıt ihtiyacını azaltır.

Otomatik abonelikler

Otomatik abonelikleri kullanmanızı öneririz. Bu özelliği etkinleştirmek için belirli veri türleri için subscriberConfigs öğenizde subscriptionCreatePolicy değerini AUTOMATIC olarak ayarlayın. AUTOMATIC politikasıyla belirttiğiniz dataTypes, Google Health API'nin bildirim gönderdiği veri türleriyle aynıdır. Ancak bu veri türleri için kullanıcı izni de verilmiş olmalıdır.

Kullanıcı, AUTOMATIC politikasına sahip veri türlerine karşılık gelen kapsamlar için uygulama izni verdiğinde Google Health API, kullanıcının izin verdiği veri türleri ile kullanıcının otomatik abone yapılandırması veri türleri arasındaki kesişimden elde edilen veri türlerini otomatik olarak izler ve bu veri türleriyle ilgili bildirimler gönderir. Bu kullanıcının bu türler için yeni veriler oluşturduğu her seferde uç noktanıza bildirim gönderilir. Bu özellik, abone oluşturmadan önce veya sonra izin veren kullanıcılar için geçerlidir. Bildirimler, abone oluşturulmadan önce oluşturulan veriler için doldurulmaz.

Bir kullanıcı izni iptal ederse ilgili veri türleriyle ilgili bildirimler durdurulur. Otomatik abonelikler Google tarafından yönetilir ve tek tek listelenemez veya silinemez. Yalnızca üst abone silindiğinde kaldırılır.

Manuel abonelikler

Her kullanıcının aboneliklerini manuel olarak yönetmeyi tercih ediyorsanız subscriberConfigs bölümünde subscriptionCreatePolicy ayarını MANUAL olarak belirleyin. Bu politika ile kullanıcı abonelikleri otomatik olarak oluşturulmaz. Bu işlev, manuel abonelikleri yönetmeye yönelik API'ler kullanıma sunulduğunda kullanılacaktır. Bu API'ler kullanıma sunulana kadar AUTOMATIC abonelikleri kullanmanızı öneririz.

Bildirimler

Bir kullanıcının verileri, abone olunan bir veri türü için değiştiğinde Google Health API, abone uç noktası URL'sine bir HTTPS POST isteği gönderir.

Bildirim biçimi

Bildirim yükü, veri değişikliğiyle ilgili ayrıntıları içeren bir JSON nesnesidir. Güncellenen verileri sorgulamak için kullanabileceğiniz kullanıcı kimliği, veri türü ve zaman aralıkları bu kapsamdadır.

{
  "data": {
    "version": "1",
    "clientProvidedSubscriptionName": "subscription-name",
    "healthUserId": "health-user-id",
    "operation": "UPSERT",
    "dataType": "steps",
    "intervals": [
      {
        "physicalTimeInterval": {
          "startTime": "2026-03-0B01:29:00Z",
          "endTime": "2026-03-08T01:34:00Z"
        },
        "civilDateTimeInterval": {
          "startDateTime": {
            "date": {
              "year": 2026,
              "month": 3,
              "day": 7
            },
            "time": {
              "hours": 17,
              "minutes": 29
            }
          },
          "endDateTime": {
            "date": {
              "year": 2026,
              "month": 3,
              "day": 7
            },
            "time": {
              "hours": 17,
              "minutes": 34
            }
          }
        },
        "civilIso8601TimeInterval": {
          "startTime": "2026-03-07T17:29:00",
          "endTime": "2026-03-07T17:34:00"
        }
      }
    ]
  }
}

operation alanı, bildirimi tetikleyen değişiklik türünü gösterir:

  • UPSERT: Herhangi bir veri ekleme veya değiştirme işlemi için gönderilir.
  • DELETE: Bir kullanıcı verileri sildiğinde veya bir sistem etkinliği (ör. kullanıcının izni iptal etmesi ya da hesabını silmesi) nedeniyle veriler kaldırıldığında gönderilir.

Yeniden denemeler, bildirimlerin yinelenmesine neden olabileceğinden, özellikle UPSERT işlemleri için bildirim işleme mantığınızı idempotent yapmanızı öneririz.

clientProvidedSubscriptionName alanı benzersiz bir tanımlayıcıdır. MANUAL politikası olan aboneliklerde bu alan, abonelik oluşturulurken belirtilen, geliştirici tarafından sağlanan kalıcı abonelik adını içerir. Bu, manuel abonelikleri yönetmek için sabit bir kimlik sağlar. AUTOMATIC politikasıyla oluşturulan abonelikler için Google Health API, her bildirimde bu alan için otomatik olarak benzersiz bir tanımlayıcı (rastgele bir UUID) oluşturur ve atar. Hem manuel hem de otomatik politikalar için clientProvidedSubscriptionName eklenmesi, tüm abonelik türlerinde tutarlı bir bildirim yükü biçimi sağlar.

healthUserId, verileri değişen kullanıcının Google Health API tanımlayıcısıdır. Uygulamanız birden fazla kullanıcıyı destekliyorsa uygulamanıza izin veren tüm kullanıcılar için bildirim alabilirsiniz. Bildirim aldığınızda, hangi kullanıcının verilerinin değiştiğini belirlemek için healthUserId simgesini kullanın. Böylece, verilerini sorgulamak için kullanıcının OAuth kimlik bilgilerini kullanabilirsiniz.

Bir kullanıcının OAuth kimlik bilgilerini healthUserId ile eşlemek için getIdentity uç noktasını kullanın. Kullanıcı oryantasyonu sırasında kullanıcının kimlik bilgileriyle bu uç noktayı çağırarak healthUserId değerini alın ve bu eşlemeyi saklayın. Bu eşleme zaman içinde değişmediği için süresiz olarak önbelleğe alınabilir. Örnek için Kullanıcı kimliğini alma başlıklı makaleyi inceleyin. Bu sayede, bir bildirimdeki healthUserId temel alınarak veri sorgulanırken doğru kullanıcı kimlik bilgilerini seçebilirsiniz.

Bir bildirimi yanıtlama

Sunucunuz, bildirimlere HTTP 204 No Content durum koduyla hemen yanıt vermelidir. Zaman aşımlarını önlemek için yanıtı gönderdikten sonra bildirim yükünü eşzamansız olarak işleyin. Google Health API başka bir durum kodu alırsa veya isteğin zaman aşımı olursa bildirim daha sonra tekrar gönderilir.

Node.js (Express) örneği:

app.post('/webhook-receiver', (req, res) => {
    // 1. Immediately acknowledge the notification
    res.status(204).send();

    // 2. Process the data asynchronously in the background
    const notification = req.body;
    setImmediate(() => {
        console.log(`Update for user ${notification.data.healthUserId} of type ${notification.data.dataType}`);
        // Trigger your data retrieval logic here
    });
});

Abonelik durumu ve kurtarma

Abone uç noktanız kullanılamaz hale gelirse veya hata durum kodu (204 dışında herhangi bir kod) döndürürse Google Health API, bekleyen bildirimleri 7 güne kadar saklar ve eksponansiyel geri yükleme ile teslimatı yeniden dener.

Uç noktanız tekrar çevrimiçi olup 204 ile yanıt verdiğinde API, depolanan iletilerin birikimini otomatik olarak teslim eder. 7 günden eski bildirimler silinir ve kurtarılamaz.

Önceki
Evrensel ve uygulama bağlantıları
Sonraki
Sorun giderme