메인 콘텐츠로 건너뛰기
PATCH
curl
rotate_secret_key는 레거시 webhook_url로 전송되는 전달 내용에 서명하는 애플리케이션 수준 비밀 값만 교체합니다. 모든 webhook 대상은 각자의 secret_shared_key로 서명하며, 이 호출은 그 값을 변경하지 않습니다.
보관 기간 필드는 Business Console → App Settings → Data retention에서 설정하는 것과 같은 정책입니다. 특히 생체 인식 템플릿 보관을 포함해 변경하기 전에 Data retention을 읽어 보십시오. allowed_return_hosts는 반환 대상 등록에서 설명합니다. biometric_consent_mode(auto, always 또는 never)는 얼굴 촬영 전에 인증 흐름이 명시적 생체 정보 동의를 요청하는 시점을 설정합니다. 생체 정보 동의를 참조하십시오. 현재 값을 먼저 확인하려면 Get Webhook Configuration을 호출하십시오.

인증

x-api-key
string
header
필수

Business Console의 Developers -> API keys에서 발급받은 귀하 애플리케이션의 API 키입니다. 기본 키는 전체 접근 권한을 갖습니다. 이름이 지정된 키는 리소스별 none, read, write 범위로 권한을 제한할 수 있으며 특정 워크플로나 승인된 세션, IP 주소 목록, 만료일 등으로 제한할 수도 있습니다. 401은 키가 잘못되었거나 폐기되었거나 만료되었음을 의미합니다. 403은 키가 전송되지 않았거나, 키에 해당 리소스나 작업에 대한 접근 권한이 없거나, 요청이 허용된 IP 목록 외부 주소에서 발생했음을 의미합니다. 세션 경로에서의 404는 해당 세션이 키의 허용 워크플로 또는 상태 범위를 벗어났음을 의미합니다. 미디어 접근 권한이 없는 키는 이미지, 비디오, PDF URL을 null로 수신하며, 세션 write 권한이 없는 키는 세션 링크와 token을 null로 수신합니다. https://docs.didit.me/console/api-keys 를 참고하십시오.

본문

application/json

변경할 필드만 전송하십시오. 대상은 여기서 관리되지 않습니다.

webhook_url
string<uri> | null

레거시 애플리케이션 수준 webhook URL입니다. Didit은 애플리케이션에 활성화된 대상이 없을 때만 이를 사용하며, 그 경우에도 status.updated 및 data.updated에만 사용합니다. 이는 대상을 생성하지 않으며, 다음 대상 생성, 업데이트 또는 삭제 시 대체됩니다. webhook을 수신하려면 대신 POST /v3/webhook/destinations/로 대상을 생성하세요.

Maximum string length: 2000
webhook_version
enum<string>

레거시 webhook_url의 payload 버전입니다.

사용 가능한 옵션:
v1,
v2,
v3
rotate_secret_key
boolean
기본값:false

true는 애플리케이션 수준의 secret_shared_key를 새로운 임의의 값으로 즉시 교체하며, 새 값은 응답에 포함됩니다. 대상 비밀은 변경되지 않습니다. true로 호출할 때마다 새 비밀이 생성되므로 멱등적이지 않습니다.

capture_method
enum<string>

레거시 애플리케이션 설정입니다. 인증 흐름에서는 이를 읽지 않습니다.

사용 가능한 옵션:
MOBILE,
MOBILE_AND_DESKTOP
data_retention_months
integer | null

자동 삭제 기간(월 단위, 1개월은 30일로 계산) 또는 자동 삭제를 사용하지 않는 경우 null입니다. 변경 사항은 기존 세션에도 적용됩니다. 새로운 기간보다 오래된 모든 사용자 인증 세션은 자동으로 삭제되며, 해당 삭제는 되돌릴 수 없습니다.

필수 범위: 1 <= x <= 120
face_retention_policy
enum<string>

세션이 삭제될 때 세션의 얼굴 임베딩에 수행되는 작업입니다. retain_until_user_deleted를 사용하려면 동일한 요청에 face_retention_days가 포함되어 있거나 이미 설정되어 있어야 합니다. 변경 사항은 이후의 세션 삭제부터 적용되며, 기존 생체 인식 템플릿을 생성하거나 영구 삭제하지 않습니다.

사용 가능한 옵션:
delete_with_session,
retain_until_user_deleted
face_retention_days
integer | null

retain_until_user_deleted 적용 시 생체 인식 템플릿의 보존 기간(일)입니다.

필수 범위: 1 <= x <= 3650

호스팅 플로우 및 네이티브 SDK에서 얼굴 캡처 전 사용자에게 명시적인 생체 인식 동의를 요청하는 시점입니다. auto(기본값)는 선언된 주, 사용자의 IP, 또는 신분증 발급 국가/지역이 일리노이, 텍사스, 콜로라도에 해당하거나 사용자가 주 정보 없이 미국 내에 있는 것으로 보일 때와 같이 트리거가 적용되는 경우에만 요청합니다. always는 얼굴을 캡처하는 워크플로의 모든 사용자에게 요청합니다. never는 해당 단계를 절대 표시하지 않으며, 셀피 촬영 전에 직접 동의를 수집해야 합니다. 모든 변경 사항은 감사 로그에 기록됩니다. 생체 인식 동의를 참고하십시오.

사용 가능한 옵션:
auto,
always,
never
allowed_return_hosts
string[]

디지털 ID 지갑 반환 호스트의 전체 목록을 대체합니다. shop.example.com과 같은 순수 호스트 이름만 허용되며 스킴, 포트, 경로 또는 와일드카드는 사용할 수 없습니다. 값은 소문자로 변환되며 중복은 제거됩니다. 목록을 지우려면 []를 전송하십시오.

Maximum array length: 20
Maximum string length: 253
allowed_domains
string[]

허용된 오리진의 전체 목록을 대체합니다. 오리진(예: https://app.example.com, localhost의 경우에만 http)은 호스팅 인증 플로우가 임베드될 수 있고 세션 콜백을 통해 사용자를 다시 보낼 수 있는 위치입니다. 서버 간 호출에는 영향을 미치지 않습니다. 빈 목록은 제한이 없음을 의미합니다. Didit은 기본 포트 없이 각 오리진을 소문자로 저장합니다. 유효하지 않은 항목은 allowed_domains에서 400 오류가 발생합니다. 제한을 제거하려면 []를 전송하십시오.

Maximum array length: 50
Maximum string length: 300
예시:

응답

업데이트 후의 전체 설정으로, GET /v3/webhook/과 동일한 형태입니다. 시크릿을 교체한 경우 응답을 폐기하기 전에 새 secret_shared_key를 저장하십시오.

모든 webhook 대상과 함께 애플리케이션 수준 webhook 설정, 데이터 보존 정책 및 디지털 ID 지갑 반환 호스트를 포함합니다.

webhook_url
string<uri> | null
필수

애플리케이션 수준(레거시) webhook URL입니다. 애플리케이션에 활성화된 대상이 없을 때만 Didit이 이 URL로 전송하며, 이때는 status.updated 및 data.updated만 전송됩니다. 대상을 생성, 업데이트 또는 삭제할 때마다 가장 오래된 활성화된 대상의 URL로 설정되거나 활성화된 대상이 없으면 null로 설정됩니다.

webhook_version
enum<string>
필수

레거시 webhook_url의 payload 버전입니다. 각 대상은 자체 webhook_version을 가집니다.

사용 가능한 옵션:
v1,
v2,
v3
secret_shared_key
string
필수

애플리케이션 수준 서명 비밀(43자 URL-safe token)입니다. 레거시 webhook_url로의 전송에만 서명합니다. 각 대상은 자체 secret_shared_key로 서명합니다. API 키 호출자는 항상 전체 값을 수신합니다. read:webhooks 권한이 없는 Console 사용자는 빈 문자열을 수신합니다.

capture_method
enum<string>
필수

레거시 애플리케이션 설정입니다. 인증 흐름에서는 이를 읽지 않으며, 캡처 옵션은 워크플로별로 구성됩니다.

사용 가능한 옵션:
MOBILE,
MOBILE_AND_DESKTOP
data_retention_months
integer | null
필수

자동 삭제 기간입니다. 생성된 지 이 개월 수(1개월은 30일로 계산)를 초과한 사용자 인증 세션은 자동으로 삭제되며, 해당 삭제는 되돌릴 수 없습니다. null은 세션이 자동으로 삭제되지 않음을 의미합니다. 데이터 보존을 참조하십시오.

필수 범위: 1 <= x <= 120
face_retention_policy
enum<string>
필수

세션이 삭제될 때 세션의 얼굴 임베딩에 수행되는 작업입니다. delete_with_session(기본값)은 세션과 함께 삭제합니다. retain_until_user_deleted는 옵트인 방식의 생체 인식 템플릿 보존으로, 사용자에 연결된 이미지가 없는 생체 인식 템플릿이 보존 기간이 끝나거나 사용자가 삭제되거나 직접 영구 삭제할 때까지 별도로 관리됩니다.

사용 가능한 옵션:
delete_with_session,
retain_until_user_deleted
face_retention_days
integer | null
필수

retain_until_user_deleted 적용 시 생체 인식 템플릿의 보존 기간(일)입니다. 해당 정책이 설정된 경우 필수입니다.

필수 범위: 1 <= x <= 3650
available_events
object[]
필수

대상이 구독할 수 있는 모든 이벤트 유형과 표시 라벨입니다.

allowed_return_hosts
string[]
필수

독립형 디지털 ID 지갑 인증이 return_url을 통해 사용자를 다시 보낼 수 있는 호스트 이름(정확히 일치, HTTPS 전용)입니다. 귀사의 화이트 라벨 도메인도 항상 허용됩니다. 반환 대상 등록을 참조하십시오.

Maximum array length: 20
Maximum string length: 253
endpoints
object[]
필수

서명용 비밀을 포함한 애플리케이션의 모든 webhook 대상(오래된 순)입니다. 여기서는 읽기 전용이며, /v3/webhook/destinations/ endpoint를 통해 대상을 관리할 수 있습니다.

호스팅 플로우 및 네이티브 SDK에서 얼굴 캡처 전 사용자에게 명시적인 생체 인식 동의를 요청하는 시점입니다. auto(기본값)는 선언된 주, 사용자의 IP, 또는 신분증 발급 국가/지역이 일리노이, 텍사스, 콜로라도에 해당하거나 사용자가 주 정보 없이 미국 내에 있는 것으로 보일 때와 같이 트리거가 적용되는 경우에만 요청합니다. always는 얼굴을 캡처하는 워크플로의 모든 사용자에게 요청합니다. never는 해당 단계를 절대 표시하지 않으며, 셀피 촬영 전에 직접 동의를 수집해야 합니다. 모든 변경 사항은 감사 로그에 기록됩니다. 생체 인식 동의를 참고하십시오.

사용 가능한 옵션:
auto,
always,
never
allowed_domains
string[]

호스팅 인증 흐름이 포함될 수 있고 세션 콜백을 통해 사용자를 다시 리디렉션할 수 있는 오리진(예: https://app.example.com; http는 localhost에만 해당)입니다. 서버 간 호출에는 영향을 미치지 않습니다. 빈 목록은 제한이 없음을 의미합니다. Didit은 각 오리진을 기본 포트 없이 소문자로 저장합니다. 유효하지 않은 항목이 있으면 allowed_domains에서 400으로 실패합니다.

Maximum array length: 50
Maximum string length: 300
예시:
마지막 수정일 2026년 11월 7일