Webhook Secret은 Asleep이 발송하는 웹훅 요청에 서명을 추가할 때 사용하는 키입니다. 수신 측은 발급받은 시크릿으로 요청 서명을 검증하여 요청의 진위와 무결성을 확인할 수 있습니다.

📘

Dashboard URL

https://dashboard.asleep.ai/

🚧

시크릿은 발급 시점 단 한 번만 노출됩니다

발급 화면을 닫으면 시크릿 값을 다시 확인할 수 없습니다.
발급 즉시 안전한 위치(시크릿 매니저, 환경 변수 등)에 보관해주세요. 분실 시에는 새로 발급받아야 합니다.

시크릿 상태

목록에 표시되는 각 상태의 의미는 다음과 같습니다.

Test Webhook Secret 와 Live Webhook Secret 구분

Test API Key와 Live API Key가 분리되어 있는 것과 마찬가지로, Webhook Secret도 환경 별로 별도로 발급해야 합니다.
Test 환경으로 발급한 시크릿은 Test API Key로 생성된 세션의 웹훅에만 적용되며, Live 환경도 동일한 방식으로 분리됩니다.

📘

권장 도입 순서

1. Test 환경에서 시크릿을 발급해 검증 로직을 먼저 적용하고 동작을 확인합니다.
2. Live 환경에 별도로 시크릿을 발급해 운영에 반영합니다.

Webhook Secret 발급하기

1. 회원가입을 완료한 계정으로 로그인 하세요.

2. 대시보드의 우측 상단에 [프로필 아이콘]을 클릭하고, [Settings]를 클릭하세요.

3. Webhook Secret 블럭에서 [Generate] 버튼을 클릭하세요.

4. 생성할 환경(live 또는 test)을 선택하고 [Generate Secret] 버튼을 클릭하세요.

5. Webhook Secret이 생성되었습니다. [Copy] 버튼으로 키 값을 복사해 저장하세요.

🚧

시크릿이 외부로 유출되지 않도록 주의해주세요

시크릿이 노출된 경우 즉시 로테이션을 통해 새로운 시크릿으로 교체하고 기존 시크릿을 폐기해주세요.

Webhook Secret 회전하기 (Rotate)

보안 정책에 따라 시크릿을 주기적으로 교체하거나, 노출이 의심될 때 사용합니다. 무중단 전환을 위한 유예 기간(grace period)을 제공합니다.

🚧

Webhook Secret 로테이션은 환경별로 한 번에 하나만 진행할 수 있습니다. 이미 로테이션 중인 시크릿이 있으면 새 로테이션을 시작할 수 없습니다.

📘

로테이션 후 24시간 동안 두 시크릿이 동시에 유효합니다

로테이션 시점부터 24시간 동안 Asleep은 새 시크릿과 기존 시크릿으로 각각 계산한 두 개의 서명을 X-Asleep-Signature 헤더에 콤마로 구분해 함께 전송합니다.

예: X-Asleep-Signature: v1=abc123...,v2=def456...

24시간이 지나면 기존 시크릿이 자동으로 만료되어, 이후 발송되는 웹훅에는 새 시크릿의 서명만 포함됩니다. 수신 측은 이 기간 안에 새 시크릿으로 검증할 수 있도록 전환을 완료해 주세요.

자세한 검증 방법은 로테이션 권장 절차 를 참고해주세요.

1. Settings의 API Key 블록에서 [Current] 탭에 표시된 키 중 폐기할 시크릿의 [Rotate] 버튼을 클릭하세요.

2. 확인 다이얼로그가 나타나면 주의사항을 확인하고 [Rotate] 버튼을 클릭하세요.

3. 새 Webhook Secret이 발급되었습니다. [Copy] 버튼으로 키 값을 복사해 저장하세요.

3. 기존 시크릿은 PENDING_REVOKE 상태, 신규 시크릿은 ACTIVE 상태로 [Current] 탭에서 확인할 수 있습니다.

로테이션 권장 절차

다운타임 없이 시크릿을 교체하려면 아래 순서로 진행해 주세요.

1. 대시보드에서 로테이션을 통해 새 시크릿을 발급합니다. 이 시점부터 24시간 후 기존 시크릿이 자동으로 만료됩니다.
2. 수신 서버의 서명 검증 로직에 새 시크릿을 적용합니다.
3. 새 시크릿으로 서명 검증이 정상 동작하는지 확인합니다. 안정적인 전환을 위해 일정 시간 모니터링 하시기를 권장합니다.
4. 24시간이 경과하면 기존 시크릿이 자동으로 만료됩니다. 더 빨리 폐기하려면 대시보드에서 수동으로 폐기할 수 있습니다.

🚧

24시간 안에 수신 서버 전환을 반드시 완료해 주세요.

기존 시크릿이 만료된 이후 발송되는 웹훅은 새 시크릿으로만 서명됩니다. 수신 서버가 여전히 기존 시크릿으로 검증하고 있다면 이후 모든 웹훅 검증이 실패합니다.

Webhook Secret 폐기하기 (Revoke)

더 이상 사용하지 않는 시크릿을 제거합니다. 폐기된 시크릿으로는 더 이상 서명이 생성되지 않습니다.

🚧

모든 시크릿을 폐기하면 서명이 더 이상 포함되지 않습니다

활성 시크릿이 한 개도 없는 상태가 되면, 발송되는 웹훅 요청에서 X-Asleep-Signature, X-Asleep-Timestamp 헤더가 제외됩니다. 검증을 계속 사용하려면 반드시 새 시크릿을 먼저 발급한 뒤 폐기를 진행해주세요.

1. Settings의 API Key 블록에서 [Current] 탭에 표시된 키 중 폐기할 시크릿의 [Revoke] 버튼을 클릭하세요.

2. 확인 다이얼로그가 나타나면 주의사항을 확인하고 [Revoke] 버튼을 클릭하세요.

3. 폐기된 시크릿는 즉시 서명에 사용되지 않는 상태로 바뀌며, [History] 탭에서 발급 일자와 폐기 일자를 확인할 수 있습니다.