Langganan webhook

Google Health API memungkinkan aplikasi Anda menerima notifikasi real-time saat data kesehatan pengguna berubah. Server Anda akan menerima permintaan POST HTTPS (webhook){:target="_blank" class="external"} segera setelah data tersedia di Google Health API, bukan melakukan polling untuk mengetahui perubahan.

Jenis data yang didukung

Notifikasi webhook didukung untuk jenis data berikut:

  • Menit Zona Aktif
  • Level Aktivitas
  • Ketinggian
  • Gula Darah
  • Lemak Tubuh
  • Kalori di Zona Detak Jantung
  • Variabilitas Detak Jantung Harian
  • Zona Detak Jantung Harian
  • Saturasi Oksigen Harian
  • Laju Pernapasan Harian
  • Detak Jantung Saat Istirahat Harian
  • Derivasi Suhu Tidur Harian
  • Jarak
  • Latihan
  • Lantai
  • Detak Jantung
  • Variabilitas Detak Jantung
  • Tinggi
  • Catatan Hidrasi
  • Catatan Nutrisi
  • Ringkasan Tidur Laju Pernapasan
  • VO2 Maks Lari
  • Periode Tidak Aktif
  • Tidur
  • Langkah
  • Waktu di Zona Detak Jantung
  • Total Kalori
  • Berat

Notifikasi hanya dikirim untuk jenis data ini 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.readonly
    • https://www.googleapis.com/auth/googlehealth.activity_and_fitness.writeonly
  • Metrik Kesehatan, yang mencakup jenis data berat:
    • https://www.googleapis.com/auth/googlehealth.health_metrics_and_measurements.readonly
    • https://www.googleapis.com/auth/googlehealth.health_metrics_and_measurements.writeonly
  • Tidur, yang mencakup jenis data tidur:
    • https://www.googleapis.com/auth/googlehealth.sleep.readonly
    • https://www.googleapis.com/auth/googlehealth.sleep.writeonly

Akun Layanan IAM

Meskipun tidak wajib, sebaiknya gunakan Akun Layanan IAM saat mengonfigurasi pelanggan untuk Google Health API. Akun layanan memberikan keamanan yang lebih baik untuk workload aplikasi dibandingkan akun pengguna standar melalui fitur berikut:

  • Kredensial otomatis yang berlaku singkat: Jika terlampir ke lingkungan eksekusi Google Cloud (seperti Compute Engine, Cloud Run, atau Google Kubernetes Engine), akun layanan akan otomatis mendapatkan dan merotasi kredensial aman yang berlaku singkat. Hal ini menghilangkan risiko pengelolaan dan penyimpanan kunci statis persisten.
  • Prinsip hak istimewa terendah: Akun layanan menyediakan identitas khusus untuk workload. Anda dapat memberikan izin khusus yang diperlukan untuk mengelola endpoint pelanggan, sehingga menghindari akses yang lebih luas ke resource Google Cloud Anda.
  • Independensi siklus proses: Akun layanan beroperasi secara independen dari akun pengguna perorangan, sehingga memastikan bahwa perubahan personel tidak memengaruhi stabilitas autentikasi jangka panjang.

Menyiapkan akun layanan

Untuk mengonfigurasi aplikasi pelanggan Anda agar melakukan autentikasi menggunakan akun layanan:

  1. Buat akun layanan: Di konsol Google Cloud, buka halaman IAM & Admin project Anda untuk membuat akun layanan yang dikelola pengguna baru.
  2. Berikan peran IAM yang diperlukan: Tetapkan peran yang sesuai yang diperlukan untuk mengelola pelanggan di project Google Cloud Anda ke akun layanan.
  3. Lampirkan akun layanan ke workload Anda: Konfigurasi lingkungan yang menghosting logika pelanggan Anda agar berjalan sebagai akun layanan baru. Hal ini memungkinkan kode aplikasi Anda (seperti library klien Google API) untuk otomatis mendeteksi dan menggunakan kredensial akun layanan yang berlaku singkat saat memanggil projects.subscribers REST API.

Peran CPE

Untuk mengelola Pelanggan atau Langganan Google Health API, Anda harus memberikan peran yang sesuai ke Akun Layanan yang di-impersonate yang melakukan panggilan API. Bergantung pada tingkat akses yang diperlukan, tetapkan salah satu peran berikut:

  • Baca Google Health API
  • Editor Google Health API
  • Admin Google Health API

Pelajari peran dan izin IAM Google Health API lebih lanjut.

Mengelola pelanggan

Sebelum dapat menerima notifikasi, Anda harus mendaftarkan Pelanggan, yang mewakili 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 create endpoint. Anda harus memberikan:

  • project-id: Nomor project tempat akun layanan webhook dibuat.
  • 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])).
  • 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. Mekanisme ini harus berisi secret yang Anda berikan. Nilai secret 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 menetapkan secret ke Bearer R4nd0m5tr1ng123 untuk autentikasi Bearer, atau Basic dXNlcjpwYXNzd29yZA== untuk autentikasi Dasar.

Di subscriberConfigs, Anda harus menetapkan subscriptionCreatePolicy untuk setiap jenis data. Tetapkan ke AUTOMATIC untuk menggunakan langganan otomatis, atau MANUAL jika Anda ingin 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": {
    "secret": "Bearer example-secret-token"
  }
}

Respons

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

Mencantumkan pelanggan

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",
      "subscriberConfigs": [
        {
          "dataTypes": ["steps", "altitude", "distance", "floors", "weight"],
          "subscriptionCreatePolicy": "AUTOMATIC"
        },
        {
          "dataTypes": ["sleep"],
          "subscriptionCreatePolicy": "MANUAL"
        }
      ],
      "endpointAuthorization": {
        "authorizationTokenSet": true
      }
    }
  ],
  "totalSize": 1
}

Memperbarui pelanggan

Gunakan patch endpoint 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 Pelanggan parsial dengan nilai baru untuk kolom yang ingin Anda perbarui. Hanya kolom yang ditentukan di updateMask yang diperbarui. Jika Anda memberikan kolom di 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 yang disimpan untuk pelanggan tersebut akan ditimpa dengan daftar yang diberikan di isi permintaan. Untuk menambahkan atau menghapus konfigurasi, Anda harus memberikan kumpulan konfigurasi lengkap. 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",
  "subscriberConfigs": [
    {
      "dataTypes": ["steps", "altitude", "distance", "floors", "weight"],
      "subscriptionCreatePolicy": "AUTOMATIC"
    },
    {
      "dataTypes": ["sleep"],
      "subscriptionCreatePolicy": "MANUAL"
    }
  ]
}

Menghapus pelanggan

Gunakan delete endpoint 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. 
{}

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 ini mengirimkan dua permintaan POST otomatis ke URI endpoint Anda, menggunakan User-Agent Google-Health-API-Webhooks-Verifier, dengan isi JSON {"type": "verification"}.

  • Handshake yang Diotorisasi: Permintaan pertama dikirim dengan header Authorization yang dikonfigurasi. Server Anda harus merespons dengan status 200 OK atau 201 Created.
  • Tantangan yang Tidak Diotorisasi: 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 untuk hanya menerima nilai endpointAuthorization baru setelah mengonfirmasi bahwa langkah 2 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 Anda untuk jenis data tertentu. dataTypes yang Anda tentukan dengan kebijakan AUTOMATIC adalah jenis data yang sama dengan jenis data yang notifikasinya dikirim oleh Google Health API, 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 perpotongan antara jenis data yang diizinkan pengguna dan jenis data konfigurasi pelanggan otomatis untuk pengguna tersebut. Notifikasi kemudian dikirim ke endpoint Anda setiap kali pengguna tersebut membuat data baru untuk jenis tersebut. Hal ini berlaku untuk pengguna yang memberikan izin sebelum atau setelah Anda membuat pelanggan. Notifikasi tidak diisi ulang untuk data yang dibuat 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 pelanggan Anda dikonfigurasi dengan subscription_create_policy MANUAL untuk jenis data tertentu, Anda harus membuat dan mengelola langganan secara eksplisit untuk setiap pengguna. Langganan menautkan pengguna tertentu ke endpoint pelanggan Anda untuk kumpulan jenis data yang ditentukan. Developer dapat menggunakan API tertentu untuk:

  • Membuat langganan (manual) per healthUserId - Membuat langganan baru untuk pengguna tertentu. Metode ini mengharuskan pelanggan memiliki SubscriptionCreatePolicy yang ditetapkan ke MANUAL untuk jenis data yang diminta.
  • Memperbarui langganan (manual) - Memperbarui jenis data untuk langganan pengguna yang ada.
  • Menghapus langganan (manual) - Menghapus langganan pengguna tertentu. Setelah dihapus, endpoint pelanggan Anda tidak akan lagi menerima notifikasi untuk pengguna ini untuk jenis data terkait.
  • Mencantumkan langganan (manual) - Mencantumkan semua langganan aktif untuk pelanggan tertentu. Anda dapat memfilter hasil menurut pengguna atau jenis data.

Notifikasi

Saat data pengguna berubah untuk jenis data yang dilanggan, Google Health API akan mengirimkan permintaan POST HTTPS ke URL endpoint pelanggan.

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-08T01: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 penambahan atau modifikasi data apa pun.
  • DELETE: Dikirim saat pengguna menghapus data.

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 yang ditentukan saat langganan dibuat. Hal ini memberikan ID yang stabil untuk mengelola langganan manual. Untuk langganan yang dibuat dengan kebijakan AUTOMATIC, Google Health API akan otomatis membuat dan menetapkan ID unik (UUID acak) ke kolom ini untuk setiap notifikasi. Menyertakan 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 pengguna mana pun yang telah memberikan izin aplikasi Anda. Saat menerima notifikasi, gunakan healthUserId untuk mengidentifikasi data pengguna mana yang telah berubah, sehingga Anda dapat menggunakan kredensial OAuth mereka untuk membuat kueri data mereka.

Untuk memetakan kredensial OAuth pengguna ke healthUserId mereka, gunakan getIdentity endpoint. Panggil endpoint ini dengan kredensial pengguna selama orientasi pengguna untuk mengambil healthUserId mereka, dan simpan pemetaan ini. Pemetaan ini tidak berubah dari waktu ke waktu, sehingga dapat di-cache tanpa batas. Untuk contohnya, lihat Mendapatkan ID pengguna. Hal ini memungkinkan Anda 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 tunggu 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
    });
});

Verifikasi tanda tangan

Untuk memastikan keaslian notifikasi Webhook, payload JSON mentah dari setiap notifikasi webhook keluar ditandatangani dengan kunci pribadi menggunakan PublicKeySign Tink, yang memberikan tanda tangan berenkode Base64 di header HTTP GOOGLE-HEALTH-API-SIGNATURE dalam permintaan. Kunci penandatanganan ini otomatis dirotasi setiap 30 hari, dan keyset publik resmi yang sesuai didistribusikan sebagai file JSON di URL permanen https://www.gstatic.com/googlehealthapi/webhooks/webhooks_public_keyset.json.

Cara Memverifikasi Tanda Tangan

Menggunakan Tink (Direkomendasikan): Developer dapat memverifikasi tanda tangan menggunakan primitif PublicKeyVerify Tink. Ambil keyset publik dari URL permanen, buat instance primitif PublicKeyVerify dengan keyset, dan verifikasi header GOOGLE-HEALTH-API-SIGNATURE yang didekode terhadap payload JSON webhook mentah.

Verifikasi Manual (Tanpa Tink): Jika developer memilih untuk tidak menggunakan Tink, mereka dapat memverifikasi tanda tangan secara manual dengan mengikuti langkah-langkah berikut:

  1. Dekode Base64 header GOOGLE-HEALTH-API-SIGNATURE untuk memisahkan awalan Tink 5 byte (yang berisi awalan versi 1 byte dan keyId 4 byte) dari tanda tangan berenkode DER yang sebenarnya.
  2. Ambil keyset JSON dari https://www.gstatic.com/googlehealthapi/webhooks/webhooks_public_keyset.json.
  3. Temukan kunci yang cocok dengan keyId yang diuraikan dan dekode Base64 kolom nilainya, yang berisi Protocol Buffer EcdsaPublicKey yang diserialisasi.
  4. Ekstrak koordinat x dan y big-endian (tag Protobuf 3 dan 4) dari payload biner ini.
  5. Buat instance kunci publik ECDSA P-256 standar di library kriptografi bawaan menggunakan koordinat x dan y yang diekstrak.
  6. Verifikasi payload JSON webhook mentah terhadap tanda tangan DER yang diekstrak menggunakan algoritma SHA-256.

Status dan pemulihan pelanggan

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 kembali pengiriman dengan backoff eksponensial.

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

Error yang biasa terjadi

Kode error Pesan Deskripsi Rekomendasi
400 Bad Request (400 Permintaan Tidak Valid) Nomor project tidak valid dalam nama resource Saat menghapus atau memperbarui pelanggan menggunakan ID project Google Cloud Anda di URL permintaan, bukan nomor project. Hal ini berlaku untuk langganan webhook menggunakan endpoint projects.subscribers. Gunakan nomor project Google Cloud Anda di URL permintaan, bukan ID project.
403 Forbidden (403 Dilarang) Penelepon tidak memiliki izin Saat membuat atau mencantumkan pelanggan menggunakan ID project Google Cloud Anda di URL permintaan, bukan nomor project. Hal ini berlaku untuk langganan webhook menggunakan endpoint projects.subscribers. Gunakan nomor project Google Cloud Anda di URL permintaan, bukan ID project.

Sebelumnya
Link Universal dan Link Aplikasi
Berikutnya
Pemecahan masalah