1. 소개

Dataspace에서 웹훅 연동 시 HMAC 서명 사용에 대한 가이드입니다. 웹훅에 대한 일반적인 설명은 아래 가이드를 참고해주시기 바랍니다.

1.1 제공 기능

웹훅으로 수신한 데이터의 무결성 및 출처 인증을 위해 HMAC 서명 옵션을 제공하고 있습니다.

2. 개발 가이드

2.1. 웹훅 등록 단계에서의 HMAC 설정

웹훅을 등록할 스페이스에 Developer 권한을 가진 계정으로 접속하면, 설정 > 개발 연동 > 웹훅에서 웹훅을 등록할 수 있습니다.
웹훅 등록시 불러올 기본 값을 등록하고 관리할 수 있습니다.
- 기본 키 등록: 16자 이내의 사용자 입력 값을 웹훅 HMAC 기본 키로 등록할 수 있습니다.
- 기본 키 변경: 현재 기본 키를 사용하는 활성화 상태의 웹훅이 없는 경우 등록한 기본 키를 변경할 수 있습니다.
- 기본 키 삭제: 현재 기본 키를 사용하는 활성화 상태의 웹훅이 없는 경우 등록한 기본 키를 삭제할 수 있습니다.
  - 기본 키를 사용한 웹훅이 있다면 해당 웹훅의 상태와 관계 없이 해당 웹훅의 설정은 HMAC 키 ‘사용 안 함’으로 변경됩니다.

웹훅 등록 단계에서 HMAC 사용 여부를 선택할 수 있습니다.
- 기본 키 사용: 스페이스에서 기본으로 사용할 웹훅 HMAC 키를 설정한 경우 사용할 수 있습니다.
- 개별 키 사용: 특정 웹훅에서 사용할 HMAC 키를 직접 입력할 수 있습니다. 최대 16자까지 입력 가능합니다.
- 사용 안 함: 웹훅에서 HMAC 키를 사용하지 않습니다. 웹훅 페이로드에 HMAC 값이 구성되지 않습니다.

2.2. 웹훅으로 수신한 데이터의 인증

1) 웹훅으로 수신한 JSON Object를 아래 규칙으로 문자열로 변환합니다.

hmac 필드를 제거합니다.
필드명을 모두 소문자화합니다.
필드의 순서를 정렬합니다. (필드명 알파벳 사전순 기준으로)
JSON 규격에서 허용되는 모든 whitespace 문자를 제거합니다.

2) 위와 같이 변환된 문자열에 대한 HMAC 값을 생성합니다.

웹훅 등록 시 구성한 HMAC 키와 함께 HmacSHA256 방법으로 digest한 결과를 base64url encoding

3) 위 2번 작업의 결과로 생성된 값을 기준으로 페이로드에 구성된 hmac 필드 값을 인증합니다.

base64url 인코딩 특성상 구현체마다 padding 문자(=)의 삽입 여부가 다를 수 있습니다. 만약 직접 비교하여 인증하고자 한다면 단순 문자열 비교보다는 byte로 변환하여 비교하는 것을 권장합니다.

2.3. 웹훅으로 수신한 데이터의 인증 예제

전제조건
- HMAC 키: dswebhooksecret (웹훅 등록시 등록한 16자 이내의 사용자 지정 값)
- 웹훅으로 수신한 데이터

{
  "uuid": "uuid_example",
  "eventType": "AnswerSheetSubmitted",
  "spaceId": "spaceId_example",
  "UID": null,
  "surveyId": "surveyId_example",
  "collectGroupId": "collectGroupId_example",
  "startedAt": "2024-10-30T18:00:24",
  "submittedAt": "2024-10-30T18:10:37",

  "hmac": "TK59QttSe-ksj0NPkWoB7B6Y4IJV13CHnT2THvziJ88="
}

HMAC 값 생성과정
- HMAC 적용할 문자열의 생성
  - 웹훅으로 수신한 데이터의 정렬 결과 값이 HMAC 적용할 문자열입니다. (hmac 필드 제거, 필드명 소문자화 및 알파벳 사전순 정렬, whitespace 문자 제거)
```
{"collectgroupid":"collectGroupId_example","eventtype":"AnswerSheetSubmitted","spaceid":"spaceId_example","startedAt":"2024-10-30T18:00:24","submittedat":"2024-10-30T18:10:37","surveyid":"surveyId_example","uid":null,"uuid":"uuid_example"}
```
HMAC 값의 생성
- Base64Url(HmacSHA256("dswebhooksecret", "{HMAC 적용할 문자열}")) = "TK59QttSe-ksj0NPkWoB7B6Y4IJV13CHnT2THvziJ88="
2번 결과 생성된 값을, 웹훅으로 수신한 hmac 필드 값의 인증에 활용합니다.