웹훅 구독

Google Health API를 사용하면 사용자의 건강 데이터가 변경될 때 애플리케이션이 실시간 알림을 수신할 수 있습니다. 변경사항을 폴링하는 대신 Google Health API에서 데이터를 사용할 수 있게 되면 서버가 HTTPS POST 요청 웹훅을 수신합니다.

지원되는 데이터 유형

웹훅 알림은 다음 데이터 유형에 지원됩니다.

  • 액티브존 미닛
  • 활동 수준
  • 고도
  • 혈당
  • 체지방
  • 심박수 구간별 칼로리
  • 일일 심박 변이도
  • 일일 심박수 구간
  • 일일 산소 포화도
  • 일일 호흡수
  • 일일 안정 시 심박수
  • 일일 수면 온도 파생
  • 거리
  • 운동
  • 층수
  • 심박수
  • 심박 변이도
  • 키
  • 수분 섭취 기록
  • 영양 기록
  • 호흡수 수면 요약
  • 러닝 최대 산소 섭취량
  • 앉아 있는 시간
  • 수면
  • 단계
  • 심박수 구간별 시간
  • 무게

알림은 사용자가 다음 상응하는 범위 중 하나에 동의한 경우에만 이러한 데이터 유형에 전송됩니다.

  • 활동, 단계, 고도, 거리, 층수 데이터 유형을 포함하는:
    • https://www.googleapis.com/auth/googlehealth.activity_and_fitness.readonly
    • https://www.googleapis.com/auth/googlehealth.activity_and_fitness.writeonly
  • 무게 데이터 유형을 포함하는
      **건강 수치** :
    • https://www.googleapis.com/auth/googlehealth.health_metrics_and_measurements.readonly
    • https://www.googleapis.com/auth/googlehealth.health_metrics_and_measurements.writeonly
  • 수면 데이터 유형을 포함하는
      수면:
    • https://www.googleapis.com/auth/googlehealth.sleep.readonly
    • https://www.googleapis.com/auth/googlehealth.sleep.writeonly

IAM 서비스 계정

필수는 아니지만 Google Health API의 구독자를 구성할 때는 IAM 서비스 계정 을 사용하는 것이 좋습니다. 서비스 계정은 다음과 같은 기능을 통해 표준 사용자 계정에 비해 애플리케이션 워크로드에 더 나은 보안을 제공합니다.

  • 자동화된 단기 사용자 인증 정보: 서비스 계정은 Google Cloud 실행 환경 (예: Compute Engine, Cloud Run 또는 Google Kubernetes Engine)에 연결되면 안전한 단기 사용자 인증 정보를 자동으로 가져오고 순환합니다. 이렇게 하면 영구 정적 키를 관리하고 저장하는 위험이 제거됩니다.
  • 최소 권한의 원칙: 서비스 계정은 워크로드에 전용 ID를 제공합니다. 구독자 엔드포인트를 관리하는 데 필요한 특정 권한만 부여하여 Google Cloud 리소스에 대한 더 광범위한 액세스를 방지할 수 있습니다.
  • 수명 주기 독립성: 서비스 계정은 개별 사용자 계정과 독립적으로 작동하므로 인력 변경이 장기 인증 안정성에 영향을 미치지 않습니다.

서비스 계정 설정

서비스 계정을 사용하여 인증하도록 구독자 애플리케이션을 구성하려면 다음 단계를 따르세요.

  1. 서비스 계정 만들기: Google Cloud 콘솔에서 프로젝트의 IAM 및 관리자 페이지로 이동하여 새 사용자 관리 서비스 계정을 만듭니다.
  2. 필요한 IAM 역할 부여: 서비스 계정에 적절한 역할을 할당합니다. Google Cloud 프로젝트에서 구독자를 관리하는 데 필요합니다.
  3. 워크로드에 서비스 계정 연결: 새 서비스 계정으로 실행되도록 구독자 로직을 호스팅하는 환경을 구성합니다. 이렇게 하면 애플리케이션 코드 (예: Google API 클라이언트 라이브러리)가 projects.subscribers REST API를 호출할 때 서비스 계정의 단기 사용자 인증 정보를 자동으로 감지하고 사용할 수 있습니다.

CPE 역할

Google Health API 구독자 또는 구독을 관리하려면 API 호출을 하는 가장된 서비스 계정에 적절한 역할을 부여해야 합니다. 필요한 액세스 수준에 따라 다음 역할 중 하나를 할당합니다.

  • Google Health API 읽기
  • Google Health API 편집자
  • Google Health API 관리자

Google Health API IAM 역할 및 권한에 대해 자세히 알아보세요.

구독자 관리

알림을 받으려면 애플리케이션의 알림 엔드포인트를 나타내는 구독자를 등록해야 합니다. `projects.subscribers`에서 제공되는 REST API를 사용하여 구독자를 관리할 수 있습니다.

구독자 엔드포인트는 HTTPS (TLSv1.2 이상)를 사용해야 하며 공개적으로 액세스할 수 있어야 합니다. 구독자를 만들고 업데이트하는 동안 Google Health API는 엔드포인트 URI를 소유하고 있는지 확인하기 위해 인증 보안 질문을 실행합니다. 인증에 실패하면 구독자 생성 및 업데이트 작업이 FailedPreconditionException으로 실패합니다.

구독자 만들기

프로젝트의 새 구독자를 등록하려면 create 엔드포인트를 사용하세요. 다음 정보를 제공해야 합니다.

  • project-id: 웹훅 서비스 계정이 생성된 프로젝트 번호입니다.
  • subscriberId: 구독자에게 제공하는 고유 식별자입니다. 이 ID는 4~36자(영문 기준)여야 하며 정규 표현식([a-z]([a-z0-9-]{2,34}[a-z0-9]))과 일치해야 합니다.
  • endpointUri: 웹훅 알림의 도착 URL입니다.
  • subscriberConfigs: 알림을 수신하려는 데이터 유형과 각 데이터 유형의 구독 정책입니다.
  • endpointAuthorization: 엔드포인트의 승인 메커니즘입니다. 여기에는 제공하는 secret이 포함되어야 합니다. secret의 값은 각 알림 메시지와 함께 Authorization 헤더에 전송됩니다. 이 토큰을 사용하여 수신 요청이 Google Health API에서 온 것인지 확인할 수 있습니다. 예를 들어 Bearer 인증의 경우 secret을 Bearer R4nd0m5tr1ng123으로 설정하거나 기본 인증의 경우 Basic dXNlcjpwYXNzd29yZA==로 설정할 수 있습니다.

subscriberConfigs에서 각 데이터 유형의 subscriptionCreatePolicy를 설정해야 합니다. 자동 구독을 사용하려면 AUTOMATIC으로 설정하고 사용자 구독을 직접 관리하려면 MANUAL로 설정합니다. 각 옵션에 관한 자세한 내용은 자동 구독 및 수동 구독을 참고하세요.

요청

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

응답

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

구독자 나열

list 엔드포인트 를 사용하여 프로젝트에 등록된 모든 구독자를 검색합니다.

요청

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

응답

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

구독자 업데이트

patch 엔드포인트 를 사용하여 프로젝트의 구독자를 업데이트합니다. 업데이트할 수 있는 필드는 endpointUri, subscriberConfigs, endpointAuthorization입니다.

updateMask 쿼리 매개변수와 요청 본문을 제공하여 필드를 업데이트합니다. updateMask에는 업데이트하려는 필드 이름의 쉼표로 구분된 목록이 포함되어야 하며 필드 이름에는 카멜 케이스를 사용합니다(예: endpointUri). 요청 본문에는 업데이트하려는 필드의 새 값이 포함된 부분 구독자 객체가 포함되어야 합니다. updateMask에 지정된 필드만 업데이트됩니다. 요청 본문에 updateMask에 없는 필드를 제공하면 무시됩니다.

endpointUri 또는 endpointAuthorization을 업데이트하면 엔드포인트 확인이 실행됩니다. 자세한 내용은 엔드포인트 확인을 참고하세요.

subscriberConfigs를 업데이트할 때는 병101}병합이 아닌 전체 대체입니다. subscriberConfigs가 updateMask에 포함된 경우 해당 구독자의 저장된 모든 구성이 요청 본문에 제공된 목록으로 덮어쓰입니다. 구성을 추가하거나 삭제하려면 전체 구성 세트를 제공해야 합니다. 다른 필드를 업데이트하고 현재 구성을 유지하려면 updateMask에서 subscriberConfigs를 생략합니다.

요청

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

응답

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

구독자 삭제

delete 엔드포인트를 사용하여 프로젝트에서 구독자를 삭제합니다. 삭제된 구독자는 더 이상 알림을 수신하지 않습니다.

요청

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

응답

삭제가 성공하면 HTTP 상태 `200 OK` 가 포함된 빈 응답 본문이 반환됩니다. 
{}

엔드포인트 확인

알림 전송의 보안과 안정성을 보장하기 위해 Google Health API는 구독자를 만들거나 엔드포인트 구성 (endpointUri 또는 endpointAuthorization)을 업데이트할 때마다 필수 2단계 인증 핸드셰이크를 실행합니다. 이 프로세스는 API 호출 중에 동기식으로 실행됩니다. 서비스는 사용자 에이전트 Google-Health-API-Webhooks를 사용하여 JSON 본문 {"type": "verification"}과 함께 자동화된 POST 요청 두 개를 엔드포인트 URI로 전송합니다.

  • 승인된 핸드셰이크: 첫 번째 요청은 구성된 Authorization 헤더와 함께 전송됩니다. 서버는 200 OK 또는 201 Created 상태로 응답해야 합니다.
  • 승인되지 않은 보안 질문: 두 번째 요청은 사용자 인증 정보 없이 전송됩니다. 서버는 401 Unauthorized 또는 403 Forbidden 상태로 응답해야 합니다.

이 핸드셰이크는 엔드포인트가 활성 상태이고 보안을 올바르게 적용하고 있음을 확인합니다. 두 단계 중 하나라도 실패하면 API 요청이 FAILED_PRECONDITION 오류와 함께 실패합니다. 이 핸드셰이크가 성공한 후에만 구독자가 저장되고 건강 데이터 알림을 수신하도록 활성화됩니다.

키 순환

endpointAuthorization의 키를 순환해야 하는 경우 다음 단계를 따르세요.

  1. 이전 및 새 endpointAuthorization 값을 모두 허용하도록 엔드포인트를 구성합니다.
  2. 새 endpointAuthorization 값으로 구독자 구성을 업데이트합니다. patch 요청과 함께 ?updateMask=endpointAuthorization를 사용합니다.
  3. 2단계가 성공했는지 확인한 후 새 endpointAuthorization 값만 허용하도록 엔드포인트를 구성합니다.

사용자 구독

Google Health API를 사용하면 사용자 구독을 효율적으로 관리하여 사용자 온보딩 중에 수동 등록이 필요하지 않습니다.

자동 구독

자동 구독을 사용하는 것이 좋습니다. 이 기능을 사용 설정하려면 특정 데이터 유형의 subscriberConfigs에서 subscriptionCreatePolicy를 AUTOMATIC으로 설정합니다. AUTOMATIC 정책으로 지정하는 dataTypes는 Google Health API에서 알림을 전송하는 데이터 유형과 동일하며, 이러한 데이터 유형에 대한 사용자 동의도 부여됩니다.

사용자가 AUTOMATIC 정책이 있는 데이터 유형에 해당하는 범위에 애플리케이션 동의를 부여하면 Google Health API는 사용자 동의 후 수집된 데이터 유형과 해당 사용자의 자동 구독자 구성 데이터 유형 간의 교차점에서 발생하는 데이터 유형에 대한 알림을 자동으로 추적하고 전송합니다. 그러면 해당 사용자가 이러한 유형의 새 데이터를 생성할 때마다 알림이 엔드포인트로 전송됩니다. 이는 구독자를 만들기 전이나 후에 동의를 부여하는 사용자에게 적용됩니다. 구독자가 생성되기 전에 생성된 데이터에 대해서는 알림이 백필되지 않습니다.

사용자가 동의를 철회하면 상응하는 데이터 유형에 대한 알림이 중지됩니다. 자동 구독은 Google에서 관리하며 개별적으로 나열하거나 삭제할 수 없습니다. 상위 구독자가 삭제될 때만 삭제됩니다.

수동 구독

구독자가 특정 데이터 유형에 대해 MANUAL subscription_create_policy로 구성된 경우 각 사용자의 구독을 명시적으로 만들고 관리해야 합니다. 구독은 특정 사용자를 정의된 데이터 유형 집합의 구독자 엔드포인트에 연결합니다. 개발자는 특정 API를 사용하여 다음 작업을 할 수 있습니다.

  • healthUserId별 (수동) 구독 만들기 - 특정 사용자의 새 구독을 만듭니다. 이 메서드를 사용하려면 구독자의 SubscriptionCreatePolicy가 요청된 데이터 유형에 대해 MANUAL로 설정되어 있어야 합니다.
  • (수동) 구독 업데이트 - 기존 사용자 구독의 데이터 유형을 업데이트합니다.
  • (수동) 구독 삭제 - 특정 사용자 구독을 삭제합니다. 삭제된 후에는 구독자 엔드포인트가 연결된 데이터 유형에 대해 이 사용자의 알림을 더 이상 수신하지 않습니다.
  • (수동) 구독 나열 - 지정된 구독자의 모든 활성 구독을 나열합니다. 사용자 또는 데이터 유형별로 결과를 필터링할 수 있습니다.

알림

사용자가 구독한 데이터 유형의 데이터가 변경되면 Google Health API는 HTTPS POST 요청을 구독자 엔드포인트 URL로 전송합니다.

알림 형식

알림 페이로드는 데이터 변경에 관한 세부정보가 포함된 JSON 객체입니다. 여기에는 업데이트된 데이터를 쿼리하는 데 사용할 수 있는 사용자 ID, 데이터 유형, 시간 간격이 포함됩니다.

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

operation 필드는 알림을 트리거한 변경 유형을 나타냅니다.

  • UPSERT: 데이터 추가 또는 수정 시 전송됩니다.
  • DELETE: 사용자가 데이터를 삭제할 때 전송됩니다.

재시도로 인해 중복 알림이 전송될 수 있으므로 알림 처리 로직을 멱등적으로 만드는 것이 좋습니다(특히 UPSERT 작업의 경우).

clientProvidedSubscriptionName 필드는 고유 식별자입니다. MANUAL 정책이 있는 구독의 경우 이 필드에는 구독이 생성될 때 지정된 영구적인 개발자 제공 구독 이름이 포함됩니다. 이를 통해 수동 구독을 관리하기 위한 안정적인 ID가 제공됩니다. AUTOMATIC 정책으로 생성된 구독의 경우 Google Health API는 각 알림에 대해 이 필드에 고유 식별자 (임의 UUID)를 자동으로 생성하고 할당합니다. 수동 및 자동 정책 모두에 clientProvidedSubscriptionName을 포함하면 모든 구독 유형에서 일관된 알림 페이로드 형식이 보장됩니다.

healthUserId는 데이터가 변경된 사용자의 Google Health API 식별자입니다. 애플리케이션이 여러 사용자를 지원하는 경우 애플리케이션 동의를 부여한 모든 사용자의 알림을 수신할 수 있습니다. 알림을 수신하면 healthUserId를 사용하여 데이터가 변경된 사용자를 식별하므로 OAuth 사용자 인증 정보를 사용하여 데이터를 쿼리할 수 있습니다.

사용자의 OAuth 사용자 인증 정보를 healthUserId에 매핑하려면 getIdentity 엔드포인트를 사용하세요. 사용자 온보딩 중에 사용자 인증 정보로 이 엔드포인트를 호출하여 healthUserId를 검색하고 이 매핑을 저장합니다. 이 매핑은 시간이 지나도 변경되지 않으므로 무기한 캐시할 수 있습니다. 예를 보려면 사용자 ID 가져오기를 참고하세요. 이렇게 하면 알림의 healthUserId를 기반으로 데이터를 쿼리할 때 올바른 사용자 인증 정보를 선택할 수 있습니다.

알림 확인

서버는 HTTP 204 No Content 상태 코드로 알림에 즉시 응답해야 합니다. 시간 초과를 방지하려면 응답을 보낸 후 알림 페이로드를 비동기식으로 처리합니다. Google Health API가 다른 상태 코드를 수신하거나 요청 시간이 초과되면 나중에 알림 전송을 재시도합니다.

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

권장사항

데이터 업데이트를 안정적이고 효율적으로 처리하려면 다음 권장사항을 따르세요.

  • Subscription API 사용: 엔드포인트를 폴링하는 대신 Subscription API를 사용하여 사용자가 다운로드할 새 데이터가 있을 때 알림을 받습니다.
  • 알림을 대기열에 넣고 별도로 처리: 구독 알림을 수신할 때 대기열에 넣고 시스템의 리소스에 따라 별도로 처리합니다. 요청을 즉시 승인하여 웹훅 엔드포인트를 가볍게 유지합니다.

서명 확인

웹훅 알림의 진위성을 보장하기 위해 모든 발신 웹훅 알림의 원시 JSON 페이로드는 Tink's PublicKeySign을 사용하여 비공개 키로 서명되며, 요청의 GOOGLE-HEALTH-API-SIGNATURE HTTP 헤더에 Base64로 인코딩된 서명을 제공합니다. 이러한 서명 키는 30일마다 자동으로 순환되며 상응하는 공식 공개 키 세트는 영구 URL https://www.gstatic.com/googlehealthapi/webhooks/webhooks_public_keyset.json에서 JSON 파일로 배포됩니다.

서명을 확인하는 방법

Tink 사용 (권장): 개발자는 Tink의 PublicKeyVerify 기본 요소를 사용하여 서명을 확인할 수 있습니다. 영구 URL에서 공개 키 세트를 가져오고, 키 세트로 PublicKeyVerify 기본 요소를 인스턴스화하고, 디코딩된 GOOGLE-HEALTH-API-SIGNATURE 헤더를 원시 웹훅 JSON 페이로드와 비교하여 확인합니다.

수동 확인 (Tink 없음): 개발자가 Tink를 사용하지 않기로 선택한 경우 다음 단계에 따라 서명을 수동으로 확인할 수 있습니다.

  1. GOOGLE-HEALTH-API-SIGNATURE 헤더를 Base64로 디코딩하여 5바이트 Tink 프리픽스 (1바이트 버전 프리픽스와 4바이트 keyId 포함)를 실제 DER로 인코딩된 서명과 분리합니다.
  2. https://www.gstatic.com/googlehealthapi/webhooks/webhooks_public_keyset.json에서 JSON 키 세트를 가져옵니다.
  3. 파싱된 keyId와 일치하는 키를 찾고 직렬화된 EcdsaPublicKey 프로토콜 버퍼가 포함된 값 필드를 Base64로 디코딩합니다.
  4. 이 바이너리 페이로드에서 빅 엔디언 x 및 y 좌표 (Protobuf 태그 3 및 4)를 추출합니다.
  5. 추출된 x 및 y 좌표를 사용하여 기본 제공 암호화 라이브러리에서 표준 ECDSA P-256 공개 키를 인스턴스화합니다.
  6. SHA-256 알고리즘을 사용하여 추출된 DER 서명과 원시 웹훅 JSON 페이로드를 비교하여 확인합니다.

구독자 상태 및 복구

구독자 엔드포인트를 사용할 수 없게 되거나 오류 상태 코드(204 이외의 코드)를 반환하면 Google Health API는 최대 7일 동안 대기 중인 알림을 저장하고 지수 백오프를 사용하여 전송을 재시도합니다.

엔드포인트가 다시 온라인 상태가 되고 204로 응답하면 API는 저장된 메시지 백로그를 자동으로 전송합니다. 7일이 지난 알림은 삭제되며 복구할 수 없습니다.

일반적인 오류

오류 코드 메시지 설명 추천
400 잘못된 요청 리소스 이름의 프로젝트 번호가 잘못되었습니다. 프로젝트 번호 대신 요청 URL에서 Google Cloud 프로젝트 ID를 사용하여 구독자를 삭제하거나 업데이트하는 경우입니다. 이는 projects.subscribers 엔드포인트를 사용하는 웹훅 구독에 적용됩니다. 프로젝트 ID가 아닌 요청 URL에서 Google Cloud 프로젝트 번호를 사용합니다.
403 금지됨 호출자에게 권한이 없습니다 프로젝트 번호 대신 요청 URL에서 Google Cloud 프로젝트 ID를 사용하여 구독자를 만들거나 나열하는 경우입니다. 이는 projects.subscribers 엔드포인트를 사용하는 웹훅 구독에 적용됩니다. 프로젝트 ID가 아닌 요청 URL에서 Google Cloud 프로젝트 번호를 사용합니다.

이전
범용 링크 및 앱 링크
다음
문제 해결