Langganan webhook


Google Health API memungkinkan aplikasi Anda menerima notifikasi real-time saat data kesehatan pengguna berubah. Daripada melakukan polling untuk mengetahui perubahan, server Anda menerima permintaan POST HTTPS (webhook) segera setelah data tersedia di Google Health API.

Jenis data yang didukung

Notifikasi webhook didukung untuk jenis data berikut:

  • Langkah
  • Ketinggian
  • Jarak
  • Lantai
  • Berat
  • Tidur

Notifikasi untuk jenis data ini hanya dikirim jika pengguna telah memberikan izin untuk salah satu cakupan yang sesuai:

  • Aktivitas, yang mencakup jenis data langkah, ketinggian, jarak, dan lantai:
    • https://www.googleapis.com/auth/googlehealth.activity_and_fitness
    • https://www.googleapis.com/auth/googlehealth.activity_and_fitness.readonly
  • Metrik Kesehatan, yang mencakup jenis data berat:
    • https://www.googleapis.com/auth/googlehealth.health_metrics_and_measurements
    • https://www.googleapis.com/auth/googlehealth.health_metrics_and_measurements.readonly
  • Sleep, yang mencakup jenis data tidur:
    • https://www.googleapis.com/auth/googlehealth.sleep
    • https://www.googleapis.com/auth/googlehealth.sleep.readonly

Mengelola subscriber

Sebelum dapat menerima notifikasi, Anda harus mendaftarkan Pelanggan, yang merepresentasikan endpoint notifikasi aplikasi Anda. Anda dapat mengelola pelanggan menggunakan REST API yang tersedia di projects.subscribers.

Endpoint pelanggan Anda harus menggunakan HTTPS (TLSv1.2+) dan dapat diakses secara publik. Selama pembuatan dan pembaruan pelanggan, Google Health API melakukan tantangan verifikasi untuk memastikan Anda memiliki URI endpoint. Jika verifikasi gagal, operasi pembuatan dan pembaruan pelanggan akan gagal dengan FailedPreconditionException.

Membuat pelanggan

Untuk mendaftarkan pelanggan baru untuk project Anda, gunakan endpoint create. Anda harus memberikan:

  • endpointUri: URL tujuan untuk notifikasi webhook.
  • subscriberConfigs: Jenis data yang ingin Anda terima notifikasinya, dan kebijakan langganan untuk setiap jenis data.
  • endpointAuthorization: Mekanisme otorisasi untuk endpoint Anda. authorization_token ini harus berisi authorization_token yang Anda berikan. Nilai authorization_token dikirim di header Authorization dengan setiap pesan notifikasi. Anda dapat menggunakan token ini untuk memverifikasi bahwa permintaan masuk berasal dari Google Health API. Misalnya, Anda dapat menyetel authorization_token ke Bearer R4nd0m5tr1ng123 untuk autentikasi Bearer, atau Basic dXNlcjpwYXNzd29yZA== untuk autentikasi Dasar.
  • subscriberId: ID unik yang Anda berikan untuk pelanggan. ID ini harus terdiri dari 4 hingga 36 karakter, dan cocok dengan ekspresi reguler ([a-z]([a-z0-9-]{2,34}[a-z0-9])).

Di subscriberConfigs, Anda harus menetapkan subscriptionCreatePolicy untuk setiap jenis data. Setel ke AUTOMATIC untuk menggunakan langganan otomatis, atau MANUAL jika Anda berencana mengelola langganan pengguna sendiri. Lihat langganan otomatis dan langganan manual untuk mengetahui detail selengkapnya tentang setiap opsi.

Permintaan

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"
  }
}

Respons

{
  "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
  }
}

Mencantumkan subscriber

Gunakan endpoint list untuk mengambil semua pelanggan yang terdaftar untuk project Anda.

Permintaan

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

Respons

{
  "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": ""
}

Memperbarui pelanggan

Gunakan endpoint patch untuk memperbarui pelanggan di project Anda. Kolom yang dapat diperbarui adalah endpointUri, subscriberConfigs, dan endpointAuthorization.

Anda memperbarui kolom dengan memberikan parameter kueri updateMask dan isi permintaan. updateMask harus berisi daftar nama kolom yang dipisahkan koma yang ingin Anda perbarui, menggunakan camel case untuk nama kolom (misalnya, endpointUri). Isi permintaan harus berisi objek Subscriber parsial dengan nilai baru untuk kolom yang ingin Anda perbarui. Hanya kolom yang ditentukan di updateMask yang diperbarui. Jika Anda memberikan kolom dalam isi permintaan yang tidak ada di updateMask, kolom tersebut akan diabaikan.

Jika Anda memperbarui endpointUri atau endpointAuthorization, verifikasi endpoint akan dilakukan. Lihat Verifikasi endpoint untuk mengetahui detailnya.

Saat memperbarui subscriberConfigs, perhatikan bahwa ini adalah penggantian penuh, bukan penggabungan. Jika subscriberConfigs disertakan dalam updateMask, semua konfigurasi tersimpan untuk pelanggan tersebut akan diganti dengan daftar yang diberikan dalam isi permintaan. Untuk menambahkan atau menghapus konfigurasi, Anda harus memberikan kumpulan lengkap konfigurasi. Jika Anda memperbarui kolom lain dan ingin mempertahankan konfigurasi saat ini, hapus subscriberConfigs dari updateMask.

Permintaan

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

Respons

{
  "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
  }
}

Verifikasi endpoint

Untuk memastikan keamanan dan keandalan pengiriman notifikasi Anda, Google Health API melakukan handshake verifikasi dua langkah wajib setiap kali Anda membuat pelanggan atau memperbarui konfigurasi endpoint-nya (endpointUri atau endpointAuthorization). Proses ini dilakukan secara sinkron selama panggilan API. Layanan mengirim dua permintaan POST otomatis ke URI endpoint Anda, menggunakan User-Agent Google-Health-API-Webhooks-Verifier, dengan isi JSON {"type": "verification"}.

  • Handshake yang Sah: Permintaan pertama dikirim dengan header Authorization yang dikonfigurasi. Server Anda harus merespons dengan status 200 OK atau 201 Created.
  • Tantangan Tidak Sah: Permintaan kedua dikirim tanpa kredensial. Server Anda harus merespons dengan status 401 Unauthorized atau 403 Forbidden.

Handshake ini mengonfirmasi bahwa endpoint Anda aktif dan menerapkan keamanan dengan benar. Jika salah satu langkah gagal, permintaan API akan gagal dengan error FAILED_PRECONDITION. Hanya setelah handshake ini berhasil, pelanggan Anda akan disimpan dan diaktifkan untuk menerima notifikasi data kesehatan.

Rotasi kunci

Jika Anda perlu merotasi kunci untuk endpointAuthorization, ikuti langkah-langkah berikut:

  1. Konfigurasi endpoint Anda untuk menerima nilai endpointAuthorization lama dan baru.
  2. Perbarui konfigurasi pelanggan dengan nilai endpointAuthorization baru menggunakan permintaan patch dengan ?updateMask=endpointAuthorization.
  3. Konfigurasi endpoint Anda agar hanya menerima nilai endpointAuthorization baru setelah mengonfirmasi bahwa langkah 2 berhasil.

Menghapus pelanggan

Gunakan endpoint delete untuk menghapus pelanggan dari project Anda. Setelah dihapus, pelanggan tidak akan lagi menerima notifikasi.

Permintaan

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

Respons

Isi respons kosong dengan status HTTP `200 OK` akan ditampilkan jika penghapusan berhasil. 
{}

Langganan pengguna

Google Health API membantu Anda mengelola langganan pengguna secara efisien, sehingga mengurangi kebutuhan pendaftaran manual selama orientasi pengguna.

Langganan otomatis

Sebaiknya gunakan langganan otomatis. Untuk mengaktifkan fitur ini, tetapkan subscriptionCreatePolicy ke AUTOMATIC di subscriberConfigs untuk jenis data tertentu. dataTypes yang Anda tentukan dengan kebijakan AUTOMATIC adalah jenis data yang sama dengan yang dikirimkan oleh Google Health API untuk notifikasi, asalkan izin pengguna juga diberikan untuk jenis data tersebut.

Saat pengguna memberikan izin aplikasi untuk cakupan yang sesuai dengan jenis data dengan kebijakan AUTOMATIC, Google Health API akan otomatis melacak dan mengirimkan notifikasi untuk jenis data yang dihasilkan dari persimpangan antara jenis data yang diizinkan pengguna dan jenis data konfigurasi pelanggan otomatis untuk pengguna tersebut. Kemudian, notifikasi akan dikirim ke endpoint Anda setiap kali pengguna tersebut membuat data baru untuk jenis tersebut. Cara ini berfungsi untuk pengguna yang memberikan izin sebelum atau setelah Anda membuat pelanggan. Notifikasi tidak diisi ulang untuk data yang dihasilkan sebelum pelanggan dibuat.

Jika pengguna mencabut izin, notifikasi untuk jenis data yang sesuai akan berhenti. Langganan otomatis dikelola oleh Google dan tidak dapat dicantumkan atau dihapus satu per satu; langganan otomatis hanya dihapus saat pelanggan induk dihapus.

Langganan manual

Jika Anda lebih memilih mengelola langganan untuk setiap pengguna secara manual, tetapkan subscriptionCreatePolicy ke MANUAL di subscriberConfigs. Dengan kebijakan ini, langganan pengguna tidak dibuat secara otomatis. Fungsi ini akan digunakan pada masa mendatang saat API untuk mengelola langganan manual tersedia. Sampai API ini tersedia, sebaiknya gunakan AUTOMATIC langganan.

Notifikasi

Saat data pengguna berubah untuk jenis data yang disubscribe, Google Health API mengirim permintaan POST HTTPS ke URL endpoint subscriber.

Format notifikasi

Payload notifikasi adalah objek JSON yang berisi detail tentang perubahan data. Hal ini mencakup ID pengguna, jenis data, dan interval waktu, yang dapat Anda gunakan untuk membuat kueri data yang diperbarui.

{
  "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"
        }
      }
    ]
  }
}

Kolom operation menunjukkan jenis perubahan yang memicu notifikasi:

  • UPSERT: Dikirim untuk setiap penambahan atau modifikasi data.
  • DELETE: Dikirim saat pengguna menghapus data, atau saat data dihapus karena peristiwa sistem, seperti pengguna mencabut izin atau menghapus akunnya.

Sebaiknya buat logika penanganan notifikasi Anda menjadi idempoten, terutama untuk operasi UPSERT, karena percobaan ulang dapat menyebabkan notifikasi duplikat dikirim.

Kolom clientProvidedSubscriptionName adalah ID unik. Untuk langganan dengan kebijakan MANUAL, kolom ini berisi nama langganan persisten yang disediakan developer dan ditentukan saat langganan dibuat. Tindakan ini memberikan ID stabil untuk mengelola langganan manual. Untuk langganan yang dibuat dengan kebijakan AUTOMATIC, Google Health API secara otomatis membuat dan menetapkan ID unik (UUID acak) ke kolom ini untuk setiap notifikasi. Mencakup clientProvidedSubscriptionName untuk kebijakan manual dan otomatis memastikan format payload notifikasi yang konsisten di semua jenis langganan.

healthUserId adalah ID Google Health API untuk pengguna yang datanya telah berubah. Jika aplikasi Anda mendukung beberapa pengguna, Anda dapat menerima notifikasi untuk setiap pengguna yang telah memberikan izin ke aplikasi Anda. Saat Anda menerima notifikasi, gunakan healthUserId untuk mengidentifikasi data pengguna mana yang telah berubah, sehingga Anda dapat menggunakan kredensial OAuth mereka untuk membuat kueri datanya.

Untuk memetakan kredensial OAuth pengguna ke healthUserId-nya, gunakan endpoint getIdentity. Panggil endpoint ini dengan kredensial pengguna selama orientasi pengguna untuk mengambil healthUserId mereka, dan simpan pemetaan ini. Pemetaan ini tidak berubah seiring waktu, sehingga dapat di-cache tanpa batas. Untuk melihat contoh, lihat Mendapatkan ID pengguna. Dengan demikian, Anda dapat memilih kredensial pengguna yang benar saat membuat kueri data berdasarkan healthUserId dalam notifikasi.

Menanggapi notifikasi

Server Anda harus segera merespons notifikasi dengan kode status HTTP 204 No Content. Untuk menghindari waktu tunggu habis, proses payload notifikasi secara asinkron setelah mengirim respons. Jika Google Health API menerima kode status lain atau waktu permintaan habis, API akan mencoba mengirim notifikasi lagi nanti.

Contoh Node.js (Express):

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
    });
});

Status dan pemulihan subscriber

Jika endpoint pelanggan Anda tidak tersedia atau menampilkan kode status error (selain 204), Google Health API akan menyimpan notifikasi yang tertunda hingga 7 hari dan mencoba lagi pengiriman dengan penundaan eksponensial.

Setelah endpoint Anda kembali online dan merespons dengan 204, API akan otomatis mengirimkan backlog pesan tersimpan. Notifikasi yang sudah lebih dari 7 hari akan dihapus dan tidak dapat dipulihkan.

Sebelumnya
Link Universal dan Link Aplikasi
Berikutnya
Pemecahan masalah