> ## Documentation Index > Fetch the complete documentation index at: https://docs.didit.me/llms.txt > Use this file to discover all available pages before exploring further. # 웹훅 설정 조회 API > 애플리케이션의 웹훅 설정을 조회하세요. 레거시 웹훅 URL과 시크릿, 대상, 구독 가능한 이벤트, 데이터 보존 정책, 지갑 반환 호스트를 확인할 수 있습니다. Didit 제공. webhook 설정 조회 API 프롬프트 프롬프트를 클립보드에 복사 \

\`Read my Didit application's webhook configuration through the Management API.

Endpoint:
GET https://verification.didit.me/v3/webhook/

Authentication:
Use the x-api-key header with my Didit API key. A scoped API key needs webhooks: read.

Goal:
\- Get every setting that controls how Didit sends webhooks for my application, plus the data-retention policy and the Digital ID wallet return hosts, in one call. Use it to audit the setup or to show the current configuration in a back office.

Behavior:
\- Didit delivers webhooks to webhook destinations (/v3/webhook/destinations/). Each destination has its own url, webhook_version, secret_shared_key and subscribed_events.
\- webhook_url, webhook_version and secret_shared_key at the top level are the application-level (legacy) webhook. Didit uses them only while the application has no enabled destination, and then only for status.updated and data.updated.
\- Every create, update or delete of a destination sets webhook_url to the URL of the oldest enabled destination, or null when none is enabled.
\- API-key callers always receive the application secret and every destination secret in full.

Example call:
curl -X GET "https://verification.didit.me/v3/webhook/" \
-H "x-api-key: YOUR_API_KEY"

What to read from the response:
\- endpoints: every destination, oldest first, with uuid, label, url, enabled, webhook_version, secret_shared_key and subscribed_events. Verify each webhook with the secret of the destination it was sent to.
\- available_events: every event type you can subscribe a destination to ({ value, label }).
\- webhook_url, webhook_version, secret_shared_key: the legacy webhook, only relevant when no destination is enabled.
\- data_retention_months (null means no automatic deletion), face_retention_policy and face_retention_days: the retention policy.
\- allowed_return_hosts: hosts a Digital ID wallet verification may send the person back to.
\- allowed_domains: web origins the hosted verification flow may be embedded in and may send the user back to; empty means no restriction.
\- capture_method: MOBILE or MOBILE_AND_DESKTOP. A legacy setting with no effect; capture options are set per workflow.

Failure modes:
\- 401: { "detail": "This API key has expired." }
\- 403: { "detail": "You do not have permission to perform this action." } for a missing key (a wrong, revoked or expired key gets 401); { "detail": "This API key has no read access to webhooks." } for a scoped key without webhooks: read.
\- 429: more than 600 GET requests per minute with this key; wait for Retry-After.

Side effects: none. This is a pure read, and the response contains signing secrets: never log it.

For the full integration shape, see /integration/integration-prompt.`

\
붙여넣을 곳 이 엔드포인트는 webhook 대상이 도입되기 전의 애플리케이션 수준 webhook과 webhook 대상 목록을 반환합니다. Didit은 webhook을 [webhook 대상](https://docs.didit.me/ko/management-api/webhook/list-destinations.md)으로 전송하며, 각 webhook은 고유한 `secret_shared_key`로 서명됩니다. 최상위 `webhook_url`, `webhook_version`, `secret_shared_key`는 활성화된 webhook 대상이 없는 동안에만 사용되며, 이 경우에도 `status.updated` 및 `data.updated`에만 사용됩니다.> [!WARNING] > > 응답에는 애플리케이션의 모든 서명용 비밀 값이 포함됩니다. 로그와 클라이언트 측 코드에 남기지 마십시오.이 설정을 변경하려면 [webhook 설정 업데이트](https://docs.didit.me/ko/management-api/webhook/update-config.md)를 사용하십시오. 서명 검증과 payload에 대해서는 [webhook 가이드](https://docs.didit.me/ko/integration/webhooks.md)를 참조하십시오. 보존 필드에 대해서는 [데이터 보존](https://docs.didit.me/ko/console/data-retention.md)을 참조하십시오. ## OpenAPI ````yaml ko/openapi-25.json GET /v3/webhook/ openapi: 3.0.0 info: version: 3.0.0 title: Didit Verification API description: 신분증 인증 API입니다. x-api-key 헤더로 인증합니다. servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/webhook/: get: tags: - Webhook summary: webhook 구성 가져오기 description: >- 한 번의 호출로 애플리케이션의 webhook 설정을 반환합니다. 서명 비밀이 포함된 각 [webhook 대상](https://docs.didit.me/ko/management-api/webhook/list-destinations), 대상이 구독할 수 있는 이벤트 유형, 애플리케이션 수준(레거시) webhook URL, 버전 및 비밀, 데이터 및 생체 인식 템플릿 보존 정책, Digital ID 지갑 반환 호스트가 포함됩니다. Didit은 각각 자체 `secret_shared_key`로 서명된 webhook을 대상에 전송합니다. 최상위 `webhook_url`, `webhook_version` 및 `secret_shared_key`는 활성화된 대상이 없을 때만 사용되며, 그 경우에도 `status.updated` 및 `data.updated`에 대해서만 사용됩니다. 응답에 서명 비밀이 포함되어 있으므로 로그나 클라이언트 측 코드에 노출되지 않도록 주의하십시오. 범위가 지정된 API 키에는 `webhooks: read` 권한이 필요합니다. operationId: get_webhook_config parameters: [] responses: '200': description: webhook 구성입니다. content: application/json: schema: $ref: '#/components/schemas/WebhookConfig' examples: One destination: value: webhook_url: https://yourapp.com/webhooks/didit webhook_version: v3 secret_shared_key: dGhpcy1pcy10aGUtYXBwLWxldmVsLXNlY3JldC0wMDA capture_method: MOBILE data_retention_months: 24 face_retention_policy: delete_with_session face_retention_days: null biometric_consent_mode: auto available_events: - value: status.updated label: Session status updated - value: data.updated label: Session data updated - value: user.status.updated label: User status updated - value: user.data.updated label: User data updated - value: business.status.updated label: Business status updated - value: business.data.updated label: Business data updated - value: activity.created label: Activity created - value: transaction.created label: Transaction created - value: transaction.status.updated label: Transaction status updated - value: travel_rule.status.updated label: Travel Rule Status Updated - value: workflow.compliance_changed label: Workflow Compliance Changed allowed_return_hosts: - shop.example.com endpoints: - uuid: 11111111-2222-3333-4444-555555555555 label: Production session webhooks url: https://yourapp.com/webhooks/didit enabled: true webhook_version: v3 secret_shared_key: dGhpcy1pcy1hbi1leGFtcGxlLXNlY3JldC0wMDAwMDA subscribed_events: - status.updated - data.updated created_at: '2026-01-04T08:00:00.000000Z' updated_at: '2026-04-22T14:09:11.523671Z' '401': description: >- API 키가 만료되었습니다. 생성 시 설정된 만료일이 지났습니다. 잘못되었거나 취소된 키도 `401`을 수신하며, 누락된 키는 `403`을 수신합니다. content: application/json: schema: type: object properties: detail: type: string description: 사람이 읽기 쉬운 오류 메시지입니다. examples: Expired key: value: detail: This API key has expired. '403': description: >- 요청이 허용되지 않습니다. `x-api-key`가 누락되었거나 유효하지 않거나 폐기된 경우 `You do not have permission to perform this action.`을 수신합니다. 이 endpoint에 필요한 접근 권한이 없는 범위 지정 키는 누락된 권한을 명시하는 메시지를 수신하며, IP 허용 목록 외부에서 사용된 키는 `This API key can't be used from this IP address.`를 수신합니다. content: application/json: schema: type: object properties: detail: type: string description: 사람이 읽기 쉬운 오류 메시지입니다. examples: Missing or invalid key: value: detail: You do not have permission to perform this action. Scoped key without webhooks read: value: detail: This API key has no read access to webhooks. Outside the IP allowlist: value: detail: This API key can't be used from this IP address. '429': description: >- 속도 제한 초과: 이 API 키의 현재 1분 시간 창에서 600개를 초과하는 GET 요청이 발생했습니다. 재시도하기 전에 `Retry-After`초 동안 대기하세요. headers: Retry-After: description: 재시도하기 전 대기할 시간(초)입니다. schema: type: integer minimum: 1 example: 30 X-RateLimit-Limit: description: 1분 동안 허용되는 요청 수(600)입니다. schema: type: integer example: 600 X-RateLimit-Remaining: description: 현재 윈도우에 남은 요청 수입니다. schema: type: integer example: 0 X-RateLimit-Reset: description: 현재 윈도우가 리셋되는 Unix 시간(초)입니다. schema: type: integer example: 1792056120 X-RateLimit-Scope: description: 초과된 예산의 이름입니다. schema: type: string example: generic-get content: application/json: schema: type: object properties: detail: type: string description: 사람이 읽기 쉬운 오류 메시지입니다. examples: Throttled: value: detail: >- GET request rate limit exceeded. You can make up to 600 requests per minute. security: - ApiKeyAuth: [] x-codeSamples: - lang: curl label: curl source: |- curl -X GET 'https://verification.didit.me/v3/webhook/' \ -H 'x-api-key: YOUR_API_KEY' - lang: python label: Python source: |- from didit import Didit # Reads DIDIT_API_KEY. client = Didit() result = client.webhooks.retrieve_config() print(result) - lang: javascript label: Node.js source: |- import Didit from "@didit-protocol/sdk-node"; // Reads DIDIT_API_KEY. const didit = new Didit(); const result = await didit.webhooks.retrieveConfig(); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Webhooks.RetrieveConfig(ctx)\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" - lang: java label: Java source: |- import me.didit.Didit; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.webhooks().retrieveConfig(); System.out.println(result); - lang: php label: PHP source: |- webhooks->retrieveConfig(); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.webhooks.retrieve_config puts result.to_h - lang: csharp label: .NET source: |- using System; using System.Text.Json; using Didit; // Reads DIDIT_API_KEY. using var client = new DiditClient(); var result = await client.Webhooks.RetrieveConfigAsync(); Console.WriteLine(JsonSerializer.Serialize(result)); components: schemas: WebhookConfig: type: object description: >- 모든 webhook 대상과 함께 애플리케이션 수준 webhook 설정, 데이터 보존 정책 및 디지털 ID 지갑 반환 호스트를 포함합니다. required: - webhook_url - webhook_version - secret_shared_key - capture_method - data_retention_months - face_retention_policy - face_retention_days - available_events - allowed_return_hosts - endpoints properties: webhook_url: type: string format: uri nullable: true description: >- 애플리케이션 수준(레거시) webhook URL입니다. 애플리케이션에 활성화된 대상이 없을 때만 Didit이 이 URL로 전송하며, 이때는 `status.updated` 및 `data.updated`만 전송됩니다. 대상을 생성, 업데이트 또는 삭제할 때마다 가장 오래된 활성화된 대상의 URL로 설정되거나 활성화된 대상이 없으면 `null`로 설정됩니다. webhook_version: type: string enum: - v1 - v2 - v3 description: 레거시 `webhook_url`의 payload 버전입니다. 각 대상은 자체 `webhook_version`을 가집니다. secret_shared_key: type: string description: >- 애플리케이션 수준 서명 비밀(43자 URL-safe token)입니다. 레거시 `webhook_url`로의 전송에만 서명합니다. 각 대상은 자체 `secret_shared_key`로 서명합니다. API 키 호출자는 항상 전체 값을 수신합니다. `read:webhooks` 권한이 없는 Console 사용자는 빈 문자열을 수신합니다. capture_method: type: string enum: - MOBILE - MOBILE_AND_DESKTOP description: 레거시 애플리케이션 설정입니다. 인증 흐름에서는 이를 읽지 않으며, 캡처 옵션은 워크플로별로 구성됩니다. data_retention_months: type: integer nullable: true minimum: 1 maximum: 120 description: >- 자동 삭제 기간입니다. 생성된 지 이 개월 수(1개월은 30일로 계산)를 초과한 사용자 인증 세션은 자동으로 삭제되며, 해당 삭제는 되돌릴 수 없습니다. `null`은 세션이 자동으로 삭제되지 않음을 의미합니다. [데이터 보존](https://docs.didit.me/ko/console/data-retention)을 참조하십시오. face_retention_policy: type: string enum: - delete_with_session - retain_until_user_deleted description: >- 세션이 삭제될 때 세션의 얼굴 임베딩에 수행되는 작업입니다. `delete_with_session`(기본값)은 세션과 함께 삭제합니다. `retain_until_user_deleted`는 옵트인 방식의 [생체 인식 템플릿 보존](https://docs.didit.me/ko/console/data-retention#생체-인식-템플릿-보존)으로, 사용자에 연결된 이미지가 없는 생체 인식 템플릿이 보존 기간이 끝나거나 사용자가 삭제되거나 직접 영구 삭제할 때까지 별도로 관리됩니다. face_retention_days: type: integer nullable: true minimum: 1 maximum: 3650 description: >- `retain_until_user_deleted` 적용 시 생체 인식 템플릿의 보존 기간(일)입니다. 해당 정책이 설정된 경우 필수입니다. biometric_consent_mode: type: string enum: - auto - always - never description: >- 호스팅 플로우 및 네이티브 SDK에서 얼굴 캡처 전 사용자에게 명시적인 생체 인식 동의를 요청하는 시점입니다. `auto`(기본값)는 선언된 주, 사용자의 IP, 또는 신분증 발급 국가/지역이 일리노이, 텍사스, 콜로라도에 해당하거나 사용자가 주 정보 없이 미국 내에 있는 것으로 보일 때와 같이 트리거가 적용되는 경우에만 요청합니다. `always`는 얼굴을 캡처하는 워크플로의 모든 사용자에게 요청합니다. `never`는 해당 단계를 절대 표시하지 않으며, 셀피 촬영 전에 직접 동의를 수집해야 합니다. 모든 변경 사항은 감사 로그에 기록됩니다. [생체 인식 동의](https://docs.didit.me/ko/getting-started/biometric-consent)를 참고하십시오. available_events: type: array description: 대상이 구독할 수 있는 모든 이벤트 유형과 표시 라벨입니다. items: type: object required: - value - label properties: value: $ref: '#/components/schemas/WebhookEvent' label: type: string description: '표시 레이블입니다(예: `Session status updated`).' allowed_return_hosts: type: array maxItems: 20 description: >- 독립형 디지털 ID 지갑 인증이 `return_url`을 통해 사용자를 다시 보낼 수 있는 호스트 이름(정확히 일치, HTTPS 전용)입니다. 귀사의 화이트 라벨 도메인도 항상 허용됩니다. [반환 대상 등록](https://docs.didit.me/ko/standalone-apis/digital-id-wallets#반환-대상-등록)을 참조하십시오. items: type: string maxLength: 253 endpoints: type: array description: >- 서명용 비밀을 포함한 애플리케이션의 모든 webhook 대상(오래된 순)입니다. 여기서는 읽기 전용이며, `/v3/webhook/destinations/` endpoint를 통해 대상을 관리할 수 있습니다. items: $ref: '#/components/schemas/WebhookConfigDestination' allowed_domains: type: array maxItems: 50 items: type: string maxLength: 300 description: >- 호스팅 인증 흐름이 포함될 수 있고 세션 콜백을 통해 사용자를 다시 리디렉션할 수 있는 오리진(예: `https://app.example.com`; `http`는 `localhost`에만 해당)입니다. 서버 간 호출에는 영향을 미치지 않습니다. 빈 목록은 제한이 없음을 의미합니다. Didit은 각 오리진을 기본 포트 없이 소문자로 저장합니다. 유효하지 않은 항목이 있으면 `allowed_domains`에서 `400`으로 실패합니다. example: - https://app.example.com WebhookEvent: type: string description: >- 지원되는 webhook 이벤트 이름입니다. `subscribed_events`에 이 정확한 문자열을 사용해야 하며, 지원되지 않는 값은 거부됩니다. enum: - status.updated - data.updated - user.status.updated - user.data.updated - business.status.updated - business.data.updated - activity.created - transaction.created - transaction.status.updated - travel_rule.status.updated - workflow.compliance_changed - transaction_rule_suggestions.created - auth.signup - auth.login - auth.login_failed - auth.password_reset_requested - auth.password_reset_completed - auth.mfa_changed - auth.new_device - auth.account_locked - investigator.report.ready - investigator.decision.automated - investigator.decision.overridden - investigator.decision.contested - investigator.question.raised - investigator.automation.paused - investigator.rfi.answered - investigator.rfi.overdue - investigator.drift.detected - investigator.sla.breached - investigator.qa.failed - investigator.external.report.ready WebhookConfigDestination: type: object description: >- 전송 지표를 제외하고 webhook 설정에 나열된 webhook 대상입니다. `GET /v3/webhook/destinations/{destination_uuid}/`는 전송 요약을 추가합니다. required: - uuid - label - url - enabled - webhook_version - secret_shared_key - subscribed_events - created_at - updated_at properties: uuid: type: string format: uuid description: 대상 ID입니다. label: type: string maxLength: 255 description: 사람이 읽을 수 있는 이름입니다. url: type: string format: uri maxLength: 2000 description: Didit이 이벤트를 POST하는 HTTPS endpoint입니다. enabled: type: boolean description: '`false`는 이 대상으로의 전송을 일시 중지합니다.' webhook_version: type: string enum: - v1 - v2 - v3 description: 이 대상으로 전송되는 payload 버전입니다. secret_shared_key: type: string description: >- 이 대상의 서명 비밀(43자 길이의 URL 안전 token)입니다. 각 webhook을 해당 webhook이 전송된 대상의 비밀로 검증하십시오. API 키 호출자는 항상 전체 값을 수신하며, `read:webhooks` 권한이 없는 콘솔 사용자는 빈 문자열을 수신합니다. subscribed_events: type: array uniqueItems: true description: 이 대상에 전송되는 이벤트 유형입니다. 대상이 이벤트 없이 생성된 경우 비어 있으며, 이 경우 아무것도 수신하지 않습니다. items: $ref: '#/components/schemas/WebhookEvent' created_at: type: string format: date-time updated_at: type: string format: date-time securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- 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 를 참고하십시오. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.