Đăng ký webhook


Google Health API cho phép ứng dụng của bạn nhận thông báo theo thời gian thực khi dữ liệu sức khoẻ của người dùng thay đổi. Thay vì thăm dò các thay đổi, máy chủ của bạn sẽ nhận được yêu cầu POST qua HTTPS (webhook) ngay khi có dữ liệu trong Google Health API.

Loại dữ liệu được hỗ trợ

Thông báo webhook được hỗ trợ cho các loại dữ liệu sau:

  • Các bước
  • Cao độ
  • Khoảng cách
  • Tầng
  • Trọng lượng
  • Ngủ

Thông báo chỉ được gửi cho các loại dữ liệu này khi người dùng đã cấp quyền đồng ý cho một trong các phạm vi tương ứng:

  • Hoạt động, bao gồm các loại dữ liệu về bước, cao độ, khoảng cách và tầng:
    • https://www.googleapis.com/auth/googlehealth.activity_and_fitness
    • https://www.googleapis.com/auth/googlehealth.activity_and_fitness.readonly
  • Chỉ số sức khoẻ, bao gồm loại dữ liệu về trọng lượng:
    • https://www.googleapis.com/auth/googlehealth.health_metrics_and_measurements
    • https://www.googleapis.com/auth/googlehealth.health_metrics_and_measurements.readonly
  • Ngủ, bao gồm loại dữ liệu về giấc ngủ:
    • https://www.googleapis.com/auth/googlehealth.sleep
    • https://www.googleapis.com/auth/googlehealth.sleep.readonly

Quản lý người đăng ký

Trước khi có thể nhận thông báo, bạn phải đăng ký Người đăng ký. Người đăng ký đại diện cho điểm cuối thông báo của ứng dụng. Bạn có thể quản lý người đăng ký bằng API REST có tại projects.subscribers.

Điểm cuối của người đăng ký phải sử dụng HTTPS (TLSv1.2+) và có thể truy cập công khai. Trong quá trình tạo và cập nhật người đăng ký, Google Health API sẽ thực hiện một thử thách xác minh để đảm bảo bạn sở hữu URI điểm cuối. Nếu xác minh không thành công, các thao tác tạo và cập nhật người đăng ký sẽ không thành công với FailedPreconditionException.

Tạo người đăng ký

Để đăng ký người đăng ký mới cho dự án, hãy sử dụng điểm cuối create. Bạn cần cung cấp:

  • endpointUri: URL đích cho thông báo webhook.
  • subscriberConfigs: Các loại dữ liệu mà bạn muốn nhận thông báo và chính sách thuê bao cho từng loại dữ liệu.
  • endpointAuthorization: Cơ chế uỷ quyền cho điểm cuối của bạn. Cơ chế này phải chứa authorization_token mà bạn cung cấp. Giá trị của authorization_token được gửi trong tiêu đề Authorization với mỗi thông báo. Bạn có thể sử dụng mã thông báo này để xác minh rằng các yêu cầu đến là từ Google Health API. Ví dụ: bạn có thể đặt authorization_token thành Bearer R4nd0m5tr1ng123 để xác thực Bearer hoặc Basic dXNlcjpwYXNzd29yZA== để xác thực cơ bản.
  • subscriberId: Giá trị nhận dạng duy nhất mà bạn cung cấp cho người đăng ký. Mã nhận dạng này phải có từ 4 đến 36 ký tự và khớp với biểu thức chính quy ([a-z]([a-z0-9-]{2,34}[a-z0-9])).

Trong subscriberConfigs, bạn phải đặt subscriptionCreatePolicy cho từng loại dữ liệu. Đặt thành AUTOMATIC để sử dụng gói thuê bao tự động hoặc MANUAL nếu bạn dự định tự quản lý gói thuê bao của người dùng. Hãy xem gói thuê bao tự động và gói thuê bao thủ công để biết thêm thông tin chi tiết về từng lựa chọn.

Yêu cầu

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

Phản hồi

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

Liệt kê người đăng ký

Sử dụng điểm cuối list để truy xuất tất cả người đăng ký đã đăng ký cho dự án của bạn.

Yêu cầu

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

Phản hồi

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

Cập nhật người đăng ký

Sử dụng điểm cuối patch để cập nhật người đăng ký trong dự án của bạn. Các trường có thể cập nhật là endpointUri, subscriberConfigs và endpointAuthorization.

Bạn cập nhật các trường bằng cách cung cấp tham số truy vấn updateMask và nội dung yêu cầu. updateMask phải chứa danh sách được phân tách bằng dấu phẩy gồm tên trường mà bạn muốn cập nhật, sử dụng kiểu viết lạc đà (viết liền và phân tách bằng chữ cái viết hoa) cho tên trường (ví dụ: endpointUri). Nội dung yêu cầu phải chứa một đối tượng Người đăng ký một phần có các giá trị mới cho các trường mà bạn muốn cập nhật. Chỉ những trường được chỉ định trong updateMask mới được cập nhật. Nếu bạn cung cấp các trường trong nội dung yêu cầu không có trong updateMask, thì các trường đó sẽ bị bỏ qua.

Nếu bạn cập nhật endpointUri hoặc endpointAuthorization, thì quá trình xác minh điểm cuối sẽ được thực hiện. Hãy xem bài viết Xác minh điểm cuối để biết thông tin chi tiết.

Khi cập nhật subscriberConfigs, hãy lưu ý rằng đây là thao tác thay thế hoàn toàn chứ không phải thao tác hợp nhất. Nếu subscriberConfigs được đưa vào updateMask, thì tất cả cấu hình đã lưu trữ cho người đăng ký đó sẽ bị ghi đè bằng danh sách được cung cấp trong nội dung yêu cầu. Để thêm hoặc xoá cấu hình, bạn phải cung cấp toàn bộ cấu hình. Nếu bạn đang cập nhật các trường khác và muốn giữ nguyên cấu hình hiện tại, hãy bỏ qua subscriberConfigs khỏi updateMask.

Yêu cầu

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

Phản hồi

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

Xác minh điểm cuối

Để đảm bảo tính bảo mật và độ tin cậy của việc gửi thông báo, Google Health API sẽ thực hiện quy trình bắt tay xác minh hai bước bắt buộc mỗi khi bạn tạo người đăng ký hoặc cập nhật cấu hình điểm cuối (endpointUri hoặc endpointAuthorization). Quá trình này được thực hiện đồng bộ trong lệnh gọi API. Dịch vụ này gửi 2 yêu cầu POST tự động đến URI điểm cuối của bạn, sử dụng Tác nhân người dùng Google-Health-API-Webhooks-Verifier, với nội dung JSON {"type": "verification"}.

  • Bắt tay được uỷ quyền: Yêu cầu đầu tiên được gửi kèm theo tiêu đề Authorization mà bạn đã định cấu hình. Máy chủ của bạn phải phản hồi bằng trạng thái 200 OK hoặc 201 Created.
  • Thử thách không được uỷ quyền: Yêu cầu thứ hai được gửi mà không có thông tin xác thực. Máy chủ của bạn phải phản hồi bằng trạng thái 401 Unauthorized hoặc 403 Forbidden.

Quy trình bắt tay này xác nhận rằng điểm cuối của bạn đang hoạt động và thực thi chính sách bảo mật một cách chính xác. Nếu một trong hai bước không thành công, yêu cầu API sẽ không thành công và trả về lỗi FAILED_PRECONDITION. Chỉ sau khi quy trình bắt tay này thành công, người đăng ký của bạn mới được lưu và kích hoạt để nhận thông báo về dữ liệu sức khoẻ.

Xoay vòng khoá

Nếu bạn cần xoay vòng khoá cho endpointAuthorization, hãy làm theo các bước sau:

  1. Định cấu hình điểm cuối để chấp nhận cả giá trị endpointAuthorization cũ và mới.
  2. Cập nhật cấu hình người đăng ký bằng giá trị mới endpointAuthorization bằng cách sử dụng yêu cầu patch với ?updateMask=endpointAuthorization.
  3. Định cấu hình điểm cuối để chỉ chấp nhận giá trị endpointAuthorization mới sau khi xác nhận bước 2 đã thành công.

Xoá người đăng ký

Sử dụng điểm cuối delete để xoá người đăng ký khỏi dự án của bạn. Sau khi bị xoá, người đăng ký sẽ không còn nhận được thông báo nữa.

Yêu cầu

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

Phản hồi

Một nội dung phản hồi trống có trạng thái HTTP `200 OK` sẽ được trả về nếu quá trình xoá thành công. 
{}

Gói thuê bao của người dùng

Google Health API giúp bạn quản lý gói thuê bao của người dùng một cách hiệu quả, giảm nhu cầu đăng ký thủ công trong quá trình giới thiệu người dùng.

Gói thuê bao tự động

Bạn nên sử dụng gói thuê bao tự động. Để bật tính năng này, hãy đặt subscriptionCreatePolicy thành AUTOMATIC trong subscriberConfigs cho các loại dữ liệu cụ thể. dataTypes mà bạn chỉ định bằng chính sách AUTOMATIC là các loại dữ liệu giống nhau mà Google Health API gửi thông báo, miễn là sự đồng ý của người dùng cũng được cấp cho các loại dữ liệu đó.

Khi người dùng cấp quyền đồng ý cho ứng dụng đối với các phạm vi tương ứng với các loại dữ liệu có chính sách AUTOMATIC, Google Health API sẽ tự động theo dõi và gửi thông báo cho các loại dữ liệu là kết quả của giao điểm giữa các loại dữ liệu của người dùng đã đồng ý và các loại dữ liệu cấu hình người đăng ký tự động cho người dùng đó. Sau đó, thông báo sẽ được gửi đến điểm cuối của bạn bất cứ khi nào người dùng đó tạo dữ liệu mới cho các loại dữ liệu đó. Tính năng này hoạt động đối với những người dùng cấp quyền đồng ý trước hoặc sau khi bạn tạo người đăng ký. Thông báo không được bổ sung dữ liệu cũ cho dữ liệu được tạo trước khi người đăng ký được tạo.

Nếu người dùng thu hồi quyền đồng ý, thông báo cho các loại dữ liệu tương ứng sẽ dừng. Gói thuê bao tự động do Google quản lý và không thể liệt kê hoặc xoá riêng lẻ; chúng chỉ bị xoá khi người đăng ký mẹ bị xoá.

Gói thuê bao thủ công

Nếu bạn muốn quản lý gói thuê bao cho từng người dùng theo cách thủ công, hãy đặt subscriptionCreatePolicy thành MANUAL trong subscriberConfigs. Với chính sách này, gói thuê bao của người dùng sẽ không được tạo tự động. Chức năng này sẽ được sử dụng trong tương lai khi các API để quản lý gói thuê bao thủ công được cung cấp. Cho đến khi các API này được cung cấp, bạn nên sử dụng gói thuê bao AUTOMATIC.

Dịch vụ thông báo

Khi dữ liệu của người dùng thay đổi đối với một loại dữ liệu đã đăng ký, Google Health API sẽ gửi yêu cầu POST qua HTTPS đến URL điểm cuối của người đăng ký.

Định dạng thông báo

Tải trọng thông báo là một đối tượng JSON chứa thông tin chi tiết về thay đổi dữ liệu. Thông tin này bao gồm mã người dùng, loại dữ liệu và khoảng thời gian mà bạn có thể sử dụng để truy vấn dữ liệu đã cập nhật.

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

Trường operation cho biết loại thay đổi đã kích hoạt thông báo:

  • UPSERT: Được gửi cho mọi thao tác thêm hoặc sửa đổi dữ liệu.
  • DELETE: Được gửi khi người dùng xoá dữ liệu hoặc khi dữ liệu bị xoá do một sự kiện hệ thống, chẳng hạn như người dùng thu hồi quyền hoặc xoá tài khoản.

Bạn nên tạo logic xử lý thông báo bất biến, đặc biệt là đối với các thao tác UPSERT, vì việc thử lại có thể khiến thông báo trùng lặp được gửi.

Trường clientProvidedSubscriptionName là giá trị nhận dạng duy nhất. Đối với các gói thuê bao có chính sách MANUAL, trường này chứa tên gói thuê bao do nhà phát triển cung cấp và được chỉ định khi gói thuê bao được tạo. Điều này cung cấp một mã nhận dạng ổn định để quản lý gói thuê bao thủ công. Đối với các gói thuê bao được tạo bằng chính sách AUTOMATIC, Google Health API sẽ tự động tạo và chỉ định một giá trị nhận dạng duy nhất (UUID ngẫu nhiên) cho trường này đối với mỗi thông báo. Việc đưa clientProvidedSubscriptionName vào cả chính sách thủ công và tự động đảm bảo định dạng tải trọng thông báo nhất quán trên tất cả các loại gói thuê bao.

healthUserId là giá trị nhận dạng Google Health API cho người dùng có dữ liệu đã thay đổi. Nếu ứng dụng của bạn hỗ trợ nhiều người dùng, bạn có thể nhận thông báo cho bất kỳ người dùng nào đã cấp quyền đồng ý cho ứng dụng của bạn. Khi nhận được thông báo, hãy sử dụng healthUserId để xác định dữ liệu của người dùng nào đã thay đổi, để bạn có thể sử dụng thông tin xác thực OAuth của họ để truy vấn dữ liệu.

Để ánh xạ thông tin xác thực OAuth của người dùng với healthUserId, hãy sử dụng điểm cuối getIdentity. Gọi điểm cuối này bằng thông tin xác thực của người dùng trong quá trình giới thiệu người dùng để truy xuất healthUserId của họ và lưu trữ thông tin ánh xạ này. Thông tin ánh xạ này không thay đổi theo thời gian, vì vậy, bạn có thể lưu vào bộ nhớ đệm vô thời hạn. Để biết ví dụ, hãy xem bài viết Nhận mã người dùng. Điều này cho phép bạn chọn thông tin xác thực người dùng chính xác khi truy vấn dữ liệu dựa trên healthUserId trong thông báo.

Phản hồi thông báo

Máy chủ của bạn phải phản hồi thông báo bằng mã trạng thái HTTP 204 No Content ngay lập tức. Để tránh hết thời gian chờ, hãy xử lý tải trọng thông báo không đồng bộ sau khi gửi phản hồi. Nếu Google Health API nhận được bất kỳ mã trạng thái nào khác hoặc yêu cầu hết thời gian chờ, thì API này sẽ thử gửi lại thông báo sau.

Ví dụ về 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
    });
});

Trạng thái và quy trình khôi phục người đăng ký

Nếu điểm cuối của người đăng ký không hoạt động hoặc trả về mã trạng thái lỗi (bất kỳ mã nào khác 204), Google Health API sẽ lưu trữ các thông báo đang chờ xử lý trong tối đa 7 ngày và thử gửi lại bằng thuật toán thời gian chờ luỹ thừa.

Sau khi điểm cuối của bạn hoạt động trở lại và phản hồi bằng 204, API sẽ tự động gửi nhật ký các thông báo đã lưu trữ. Các thông báo cũ hơn 7 ngày sẽ bị loại bỏ và không thể khôi phục.

Trước
Đường liên kết phổ quát và đường liên kết đến ứng dụng
Tiếp
Khắc phục sự cố