> ## 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 > Didit 웹훅 대상을 수정합니다. 라벨, URL, 활성화 상태, 버전, 구독 이벤트를 변경할 수 있습니다. 프로그래밍 방식의 웹훅 관리, 호출당 과금, 계약 불필요. webhook 대상 업데이트 API 프롬프트 프롬프트를 클립보드에 복사 \

\`Update a Didit webhook destination through the Management API.

Endpoint:
PATCH https://verification.didit.me/v3/webhook/destinations/{destination_uuid}/

Authentication:
Use the x-api-key header with my Didit API key.

Goal:
\- Change a destination's label, url, enabled state, webhook_version, or subscribed_events. Send only the fields you want to change.

Path parameter:
\- destination_uuid — the destination UUID from GET /v3/webhook/destinations/.

Request body (application/json) — all fields optional:
\{
"label": "Updated label",
"url": "https://yourapp.com/webhooks/v2",
"enabled": false,
"webhook_version": "v3",
"subscribed_events": ["status.updated", "data.updated", "transaction.created"]
}

Critical semantics:
\- subscribed_events is replaced wholesale, NOT merged. To add an event, GET the current destination, append to the list, and send the full array back. Sending [] returns 400.
\- url must remain unique among the application's destinations.
\- A uuid in the body is ignored: the path names the destination.
\- webhook_version applies to future deliveries only. Already-queued deliveries use the version that was active when they were enqueued.
\- The signing secret (secret_shared_key) is NOT rotated by PATCH. Console offers a manual rotation flow. For 24 hours after a rotation, every delivery also carries X-Signature-Previous, X-Signature-V2-Previous and X-Signature-Simple-Previous, made with the replaced secret, and previous_secret_expires_at says when that ends.
\- Changing url does not move automatic retries of deliveries already made: they go to the URL the first attempt used. A manual resend goes to the destination's current URL.

Example call (replace subscription list):
curl -X PATCH "https://verification.didit.me/v3/webhook/destinations/{destination_uuid}/" \
-H "x-api-key: YOUR_API_KEY" -H "Content-Type: application/json" \
-d '{"subscribed_events": ["status.updated", "data.updated", "transaction.created"]}'

\# Pause a destination without losing config:
curl -X PATCH "https://verification.didit.me/v3/webhook/destinations/{destination_uuid}/" \
-H "x-api-key: YOUR_API_KEY" -H "Content-Type: application/json" \
-d '{"enabled": false}'

Failure modes:
\- 400 — empty subscribed_events, unknown event name, duplicate url among destinations, or invalid webhook_version.
\- 401 — missing or malformed x-api-key.
\- 403 — canonical { "detail": "You do not have permission to perform this action." } envelope.
\- 404 — destination not found in this application.

Side effects:
\- Subsequent webhook deliveries respect the new url, enabled flag, and subscribed_events list.

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

\
붙여넣을 곳 이 엔드포인트를 사용하면 대상이 webhook을 보내는 위치와 수신하는 이벤트를 변경할 수 있습니다.## `subscribed_events` 업데이트`subscribed_events`를 전송할 때는 업데이트 후에도 구독을 유지해야 하는 이벤트의 전체 목록을 제공해야 합니다. 이 배열은 이전 구독 집합을 대체합니다.```json theme={null} { "subscribed_events": [ "status.updated", "data.updated", "transaction.created", "transaction.status.updated" ] } ```지원되는 값은 다음과 같습니다.| 이벤트 | 의미 | | - | - | | `status.updated` | 사용자 인증(KYC) 또는 기업 확인(KYB) 세션의 상태가 변경되었습니다. | | `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` | Travel Rule 교환의 상태가 변경되었습니다. | | `workflow.compliance_changed` | 게시된 워크플로의 컴플라이언스 상태가 변경되었습니다. | | `transaction_rule_suggestions.created` | 규칙 제안 실행으로 새로운 규칙 변경이 제안되었습니다. |Investigator(`investigator.*`) 및 Authentication(`auth.*`) 이벤트 계열도 허용됩니다. 전체 목록은 [webhook](https://docs.didit.me/ko/integration/webhooks.md#이벤트-유형)을 참조하십시오.이벤트에 대한 자세한 설명과 일반적인 구독 집합은 [대상 생성 가이드](https://docs.didit.me/ko/management-api/webhook/create-destination.md)를 참조하십시오. ## OpenAPI ````yaml ko/openapi-25.json PATCH /v3/webhook/destinations/{destination_uuid}/ 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/destinations/{destination_uuid}/: patch: tags: - Webhook summary: webhook 대상 업데이트 description: >- webhook 대상을 업데이트합니다. **`subscribed_events`는 병합되지 않고 전체가 대체(REPLACED)됩니다**: 먼저 조회한 후 추가하여 다시 전송하십시오. 시크릿은 교체되지 않습니다. 본문의 `uuid`는 무시되며 경로에서 대상 이름을 지정합니다. operationId: update_webhook_destination parameters: - name: destination_uuid in: path required: true description: 업데이트할 webhook 대상의 UUID입니다. schema: type: string format: uuid example: 11111111-2222-3333-4444-555555555555 requestBody: required: true content: application/json: schema: type: object properties: label: type: string description: 새로운 읽기 쉬운 이름입니다. url: type: string format: uri description: 새 대상 URL입니다. 애플리케이션 내에서 고유해야 합니다. enabled: type: boolean description: 이 대상을 삭제하지 않고 전송을 일시 중지하려면 `false`로 설정합니다. webhook_version: type: string enum: - v1 - v2 - v3 description: 향후 전송에 사용할 새 payload 스키마 버전입니다. subscribed_events: $ref: '#/components/schemas/WebhookSubscribedEvents' examples: Pause destination: value: enabled: false Add transaction events: value: subscribed_events: - status.updated - data.updated - transaction.created - transaction.status.updated Move target URL: value: label: Production session webhooks v2 url: https://api.yourapp.com/webhooks/didit/v2 responses: '200': description: >- 업데이트된 webhook 대상입니다. 본문의 형태는 `GET /v3/webhook/destinations/{destination_uuid}/`와 동일합니다. content: application/json: schema: type: object properties: uuid: type: string format: uuid label: type: string url: type: string format: uri enabled: type: boolean webhook_version: type: string enum: - v1 - v2 - v3 secret_shared_key: type: string secret_last4: type: string description: >- 대상의 현재 서명 비밀의 마지막 4자로, 비밀을 서로 구분할 수 있습니다. 서명 검증에는 충분하지 않습니다. previous_secret_expires_at: type: string format: date-time nullable: true description: >- Business Console에서 대상의 서명 비밀이 교체된 후 24시간 동안 설정됩니다. 이 시점까지 해당 대상으로 이루어지는 모든 전송에는 교체된 비밀로 생성된 `X-Signature-Previous`, `X-Signature-V2-Previous`, `X-Signature-Simple-Previous`도 함께 포함됩니다([서명 검증](/ko/integration/webhooks#서명-검증) 참조). 지난 24시간 동안 교체된 적이 없으면 `null`입니다. subscribed_events: $ref: '#/components/schemas/WebhookSubscribedEvents' created_by_email: type: string nullable: true description: >- 대상을 생성한 Business Console 멤버의 이메일입니다. API 키로 생성된 대상의 경우 `null`입니다. created_by_name: type: string nullable: true description: >- 대상을 생성한 Business Console 멤버의 이름입니다. API 키로 생성된 대상의 경우 `null`입니다. created_at: type: string format: date-time updated_at: type: string format: date-time health_status: type: string enum: - healthy - degraded - failing description: >- 전송 상태입니다. `failing`: 대상이 마지막으로 성공적으로 응답한 이후 3개 이상의 연속 이벤트가 첫 번째 전송 시도에서 실패했습니다(`failing_streak` 참조). `degraded`: failing 상태는 아니지만 지난 24시간 동안 전송 시도가 실패했고 이후 시도에서도 해당 이벤트를 전송하지 못했습니다. 전송에 성공하는 재시도 또는 재발송이 발생하면 이 상태가 해제됩니다. `healthy`: 둘 다 해당하지 않습니다. `enabled`와 무관합니다. 실패한 시도는 HTTP 400 이상의 응답을 받았거나 응답이 전혀 없는 시도를 의미합니다. failing_streak: type: integer description: >- 최근 30일 이내에 대상이 마지막으로 성공적인 응답을 보낸 이후, 첫 번째 전송 시도에 실패한 연속 이벤트 수입니다. 재시도는 계산되지 않으며 재시도 또는 재발송을 포함한 성공적인 시도가 있으면 연속 실패가 종료됩니다. 마지막 성공 이후 실패한 이벤트가 없으면 `0`입니다. failing_since: type: string format: date-time nullable: true description: >- 현재 `failing_streak`의 첫 번째 실패 시도가 발생한 시점입니다. `failing_streak`가 `0`인 경우 `null`입니다. last_success_at: type: string format: date-time nullable: true description: >- 최근 30일 이내에 대상이 400 미만의 HTTP 상태로 전송에 마지막으로 응답한 시점입니다. 해당 기간 내에 응답이 없었던 경우 `null`입니다. environment: type: string enum: - live - sandbox description: 대상을 소유한 애플리케이션의 환경. summary: type: object description: >- 최근 `metrics_window_days`(30)일 동안의 전송 지표입니다. `last_delivery_at`은 시점과 관계없이 가장 최근의 시도를 나타냅니다. properties: total_deliveries: type: integer failed_deliveries: type: integer error_rate_percentage: type: integer min_response_time_ms: type: integer nullable: true avg_response_time_ms: type: integer nullable: true max_response_time_ms: type: integer nullable: true last_delivery_at: type: string format: date-time nullable: true metrics_window_days: type: integer description: 다른 요약 지표가 적용되는 기간(일 단위)입니다. 항상 `30`입니다. examples: Paused: value: uuid: 11111111-2222-3333-4444-555555555555 label: Production session webhooks url: https://yourapp.com/webhooks/didit enabled: false webhook_version: v3 secret_shared_key: tno2NTeRC1ZK3sBOYlBJDyEzBVENl3pQ1AcZyAW0xnQ secret_last4: 0xnQ previous_secret_expires_at: null subscribed_events: - status.updated - data.updated created_by_email: null created_by_name: null created_at: '2026-01-04T08:00:00Z' updated_at: '2026-05-17T11:02:55Z' health_status: healthy failing_streak: 0 failing_since: null last_success_at: '2026-05-17T09:21:18Z' environment: live summary: total_deliveries: 12453 failed_deliveries: 14 error_rate_percentage: 0 min_response_time_ms: 41 avg_response_time_ms: 187 max_response_time_ms: 2103 last_delivery_at: '2026-05-17T09:21:18Z' metrics_window_days: 30 '400': description: 유효성 검사 실패(중복된 URL, 비어 있거나 알 수 없는 이벤트 목록, 잘못된 형식의 본문). content: application/json: examples: Duplicate URL: value: url: - >- This webhook destination already exists for the application. Empty events: value: subscribed_events: - At least one subscribed event is required. '403': description: >- API 키가 누락되었거나, 형식이 잘못되었거나, 만료되었거나, 다른 애플리케이션으로 범위가 지정되었습니다. 키가 누락된 경우 `403`을 반환하고, 잘못되었거나 취소되었거나 만료된 키는 `401`을 반환합니다. content: application/json: examples: Forbidden: value: detail: You do not have permission to perform this action. '404': description: 해당 UUID를 가진 대상이 존재하지 않습니다(또는 삭제되었거나 다른 애플리케이션에 속함). content: application/json: examples: Not found: value: detail: Webhook destination not found. '429': description: 속도 제한 초과. 대기 후 재시도하세요. content: application/json: examples: Throttled: value: detail: Request was throttled. Expected available in 30 seconds. security: - ApiKeyAuth: [] x-codeSamples: - lang: curl label: curl source: >- curl -X PATCH 'https://verification.didit.me/v3/webhook/destinations/11111111-2222-3333-4444-555555555555/' \ -H 'x-api-key: YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "subscribed_events": [ "status.updated", "data.updated", "transaction.created" ] }' - lang: python label: Python source: |- from didit import Didit # Reads DIDIT_API_KEY. client = Didit() result = client.webhooks.destinations.update( "11111111-2222-3333-4444-555555555555", enabled=False, ) 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.destinations.update("11111111-2222-3333-4444-555555555555", { enabled: false, }); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Webhooks.Destinations.Update(ctx, \"11111111-2222-3333-4444-555555555555\", didit.WebhooksDestinationsUpdateParams{\n\tEnabled: didit.Bool(false),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" - lang: java label: Java source: >- import me.didit.Didit; import me.didit.types.WebhooksDestinationsUpdateParams; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.webhooks().destinations().update("11111111-2222-3333-4444-555555555555", WebhooksDestinationsUpdateParams.builder() .enabled(false) .build()); System.out.println(result); - lang: php label: PHP source: >- webhooks->destinations->update('11111111-2222-3333-4444-555555555555', [ 'enabled' => false, ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.webhooks.destinations.update( "11111111-2222-3333-4444-555555555555", enabled: false ) 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.Destinations.UpdateAsync("11111111-2222-3333-4444-555555555555", new WebhooksDestinationsUpdateParams { Enabled = false, }); Console.WriteLine(JsonSerializer.Serialize(result)); components: schemas: WebhookSubscribedEvents: type: array description: >- 이 webhook 대상의 이벤트 필터입니다. Didit은 이벤트 유형이 이 값 중 하나와 정확히 일치하는 webhook만 전송하며, 와일드카드 구독은 지원하지 않습니다. 요청을 보낼 때 목록에는 최소 하나 이상의 유효한 이벤트가 포함되어야 하며(명시적인 `[]`는 400 오류로 거부됨), 목록이 비어 있는(생성 시 필드를 생략한) 대상은 아무것도 수신하지 않습니다. 업데이트 시 목록은 병합되지 않고 전체가 대체됩니다. minItems: 1 uniqueItems: true items: $ref: '#/components/schemas/WebhookEvent' example: - status.updated - data.updated 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 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.