Langganan webhook

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

Jenis data yang didukung

Notifikasi webhook didukung untuk jenis data berikut:

  • Menit Zona Aktif
  • Tingkat Aktivitas
  • Ketinggian
  • Gula Darah
  • Lemak Tubuh
  • Kalori dalam Zona Detak Jantung
  • Variabilitas Detak Jantung Harian
  • Zona Detak Jantung Harian
  • Saturasi Oksigen Harian
  • Laju Pernapasan Harian
  • Detak Jantung saat Istirahat Harian
  • Turunan 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
  • Berat

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.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 beban kerja aplikasi dibandingkan dengan akun pengguna standar melalui fitur berikut:

  • Kredensial berjangka pendek otomatis: Saat dilampirkan ke lingkungan eksekusi Google Cloud (seperti Compute Engine, Cloud Run, atau Google Kubernetes Engine), akun layanan akan otomatis mendapatkan dan merotasi kredensial berjangka pendek yang aman. Tindakan ini menghilangkan risiko pengelolaan dan penyimpanan kunci statis persisten.
  • Prinsip hak istimewa terendah: Akun layanan menyediakan identitas khusus untuk beban kerja. Anda dapat memberi mereka hanya izin tertentu 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 mana pun, sehingga memastikan bahwa perubahan personel tidak memengaruhi stabilitas autentikasi jangka panjang.

Menyiapkan akun layanan

Untuk mengonfigurasi aplikasi pelanggan agar mengautentikasi menggunakan akun layanan:

  1. Buat akun layanan: Di konsol Google Cloud, buka halaman IAM & Admin project Anda untuk membuat akun layanan baru yang dikelola pengguna.
  2. Berikan peran IAM yang diperlukan: Tetapkan peran yang sesuai ke akun layanan yang diperlukan untuk mengelola pelanggan di project Google Cloud Anda.
  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 mendeteksi dan menggunakan kredensial berjangka pendek akun layanan secara otomatis 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 ditiru identitasnya 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 lebih lanjut peran dan izin IAM Google Health API.

Mengelola subscriber

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 endpoint create. 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. secret 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 menyetel secret ke Bearer R4nd0m5tr1ng123 untuk autentikasi Bearer, atau Basic dXNlcjpwYXNzd29yZA== untuk autentikasi Dasar.

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

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 yang disimpan 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",
  "subscriberConfigs": [
    {
      "dataTypes": ["steps", "altitude", "distance", "floors", "weight"],
      "subscriptionCreatePolicy": "AUTOMATIC"
    },
    {
      "dataTypes": ["sleep"],
      "subscriptionCreatePolicy": "MANUAL"
    }
  ]
}

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

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, 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.

Langganan pengguna

Google Health API membantu Anda mengelola langganan pengguna secara efisien, sehingga mengurangi kebutuhan pendaftaran manual selama aktivasi 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 ini 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 subscriber 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 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-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 setiap penambahan atau modifikasi data.
  • 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 dan ditentukan saat langganan dibuat. Tindakan ini memberikan ID 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. 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
    });
});

Praktik terbaik

Ikuti praktik terbaik berikut untuk memastikan penanganan update data yang andal dan efisien:

  • Gunakan Subscription API: Gunakan Subscription API untuk mendapatkan notifikasi saat pengguna memiliki data baru untuk didownload, bukan melakukan polling endpoint.
  • Mengantrekan dan memproses notifikasi secara terpisah: Saat menerima notifikasi langganan, masukkan notifikasi tersebut ke dalam antrean dan proses secara terpisah berdasarkan resource sistem Anda. Jaga agar endpoint webhook tetap ringan dengan mengonfirmasi permintaan segera.

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 yang dienkode Base64 di header HTTP GOOGLE-HEALTH-API-SIGNATURE dalam permintaan. Kunci penandatanganan ini dirotasi secara otomatis setiap 30 hari, dan set kunci 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 primitive 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. Mendekode header GOOGLE-HEALTH-API-SIGNATURE berenkode Base64 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 Buffer Protokol EcdsaPublicKey yang diserialkan.
  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 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 backoff eksponensial.

Setelah endpoint Anda kembali online dan merespons dengan 204, API akan otomatis mengirimkan backlog pesan yang disimpan. Notifikasi yang sudah lebih 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 Terlarang Pemanggil tidak memiliki izin Saat membuat atau mencantumkan pelanggan menggunakan ID project Google Cloud 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