> ## 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. # webhook 대상 생성 API > Didit에 새 webhook 대상을 등록합니다. 버전, 구독 이벤트, 대상별 서명 비밀을 설정하며, 프로그래매틱 webhook 작업을 호출당 과금으로 제공합니다. webhook 대상 생성 API 프롬프트 프롬프트를 클립보드에 복사 \

\`Register a new webhook destination for my Didit application through the Management API.

Endpoint:
POST https://verification.didit.me/v3/webhook/destinations/

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

Goal:
\- Create a destination where Didit pushes the events I subscribe to. Each destination is an independent (URL, signing secret, payload version, event subscription) tuple.

Request body (application/json):
\{
"label": "Production session webhooks",        // required, human-readable
"url": "https://yourapp.com/webhooks/didit",   // required, HTTPS URL; must be unique among the application's destinations
"enabled": true,                                 // optional, default true
"webhook_version": "v3",                        // optional, "v1" | "v2" | "v3" — v3 is current/recommended
"subscribed_events": ["status.updated", "data.updated"]  // required, at least one supported event
}

Supported subscribed_events values (no wildcard):
\- status.updated, data.updated — KYC/KYB session lifecycle.
\- user.status.updated, user.data.updated — User entity changes.
\- business.status.updated, business.data.updated — Business entity changes.
\- activity.created — accepted and covered by Try Webhook, but not delivered for live traffic today.
\- transaction.created, transaction.status.updated — Transaction monitoring events.
\- travel_rule.status.updated — a Travel Rule exchange changed status.
\- workflow.compliance_changed — a published workflow's compliance status changed.
\- transaction_rule_suggestions.created — a rule suggestion run proposed new rule changes.
\- The full list, including the Investigator and Authentication families, is at /integration/webhooks#event-types.

Critical: capture secret_shared_key from the response and store it securely.
\- The response includes secret_shared_key — this is the HMAC signing secret used to compute X-Signature, X-Signature-V2, and X-Signature-Simple headers on every webhook delivered to this URL. Verify with X-Signature-V2; X-Signature-Simple is deprecated and authenticates the envelope only.
\- Store the secret from the create response. GET /v3/webhook/destinations/{destination_uuid}/ also returns it in full to your API key, but storing it on create avoids leaking it through follow-up reads.
\- The secret is unique per-destination.
\- The rest of the 201 body has the same shape as GET /v3/webhook/destinations/{destination_uuid}/: secret_last4, health_status "healthy", a summary with zero counts and null times, and created_by_email and created_by_name set to null for a destination created with an API key.

Example call:
curl -X POST "https://verification.didit.me/v3/webhook/destinations/" \
-H "x-api-key: YOUR_API_KEY" -H "Content-Type: application/json" \
-d '{
"label": "Production session webhooks",
"url": "https://yourapp.com/webhooks/didit",
"webhook_version": "v3",
"subscribed_events": ["status.updated", "data.updated"]
}'

Signature verification quick-start (HMAC-SHA256 over the raw request body):
import hmac, hashlib
def verify(body: bytes, signature: str, secret: str) -> bool:
expected = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, signature)

Always verify against the raw request body, not the parsed JSON. See /integration/webhooks for the full v3 signature scheme.

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

Side effects:
\- A new destination is created and will start receiving deliveries for subscribed_events immediately (assuming enabled: true).
\- Not idempotent — repeated POSTs with different metadata create separate destinations.

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

\
붙여넣을 곳 webhook 대상을 사용하면 서로 다른 Didit 이벤트를 서로 다른 URL로 보낼 수 있습니다. 각 대상에는 고유한 `secret_shared_key`, `webhook_version`, `subscribed_events` 목록이 있습니다.## `subscribed_events`의 작동 방식`subscribed_events`는 정확한 이벤트 이름으로 이루어진 필수 배열입니다. Didit는 payload의 `webhook_type`이 배열의 값 중 하나와 일치하는 경우에만 이 대상으로 webhook을 전송합니다.- 최소 하나의 이벤트를 포함하세요. - 아래에 나열된 지원 이벤트 이름만 사용하세요. - 전송받고 싶은 모든 이벤트를 추가하세요. `*` 또는 `all`과 같은 와일드카드 값은 없습니다. - 제품 영역별로 다른 시스템에 전달하려면 `subscribed_events` 목록이 서로 다른 대상을 여러 개 만드세요.## 이벤트 카탈로그| 이벤트 | 구독이 필요한 경우 | | - | - | | `status.updated` | 사용자 인증(KYC) 또는 기업 확인(KYB) 세션의 상태가 변경될 때. KYB payload에는 `session_kind: "business"`와 `business_session_id`가 포함됩니다. | | `data.updated` | 세션 인증 데이터가 생성 후 수정되거나 업데이트될 때. 예를 들어 검토자가 KYC, 주소 증명, KYB 데이터를 편집한 경우입니다. | | `user.status.updated` | 사용자 엔티티의 상태가 변경될 때. 예: `ACTIVE`, `FLAGGED`, `BLOCKED`. | | `user.data.updated` | 사용자 엔티티의 프로필, 카운터, 메타데이터, 문서 또는 집계 인증 필드가 변경될 때. | | `business.status.updated` | 기업 엔티티의 상태가 변경될 때. 예: 수동 검토, KYB 결과 또는 차단 목록 조치 이후. | | `business.data.updated` | 기업 엔티티의 프로필, 카운터, 메타데이터, 등록 필드 또는 집계 인증 필드가 변경될 때. | | `activity.created` | `subscribed_events`에서 허용되며 **Try Webhook**에서 테스트할 수 있습니다. 다만 Didit는 현재 실제 트래픽에 대해서는 이 이벤트를 전송하지 않습니다. | | `transaction.created` | 거래 모니터링의 거래가 생성되고 초기 규칙 평가가 완료될 때. | | `transaction.status.updated` | 규칙, 분석가 검토, 조치, 공급자 업데이트 또는 API/콘솔 작업 이후 거래의 상태가 변경될 때. 백그라운드에서 재시도된 암호화폐 스크리닝이 완료되면 한 번 전송됩니다. | | `travel_rule.status.updated` | [Travel Rule](https://docs.didit.me/ko/transaction-monitoring/travel-rule.md) 교환의 상태가 변경될 때. | | `workflow.compliance_changed` | 게시된 워크플로의 컴플라이언스 상태가 재평가 후 변경될 때. | | `transaction_rule_suggestions.created` | 규칙 제안 실행에서 새로운 규칙 변경을 제안할 때. |`investigator.*` 및 `auth.*` 이벤트 계열도 허용됩니다. 모든 이벤트와 해당 payload는 [webhook](https://docs.didit.me/ko/integration/webhooks.md#이벤트-유형)에 나열되어 있습니다.일반적인 구독 조합:```json theme={null} { "subscribed_events": ["status.updated", "data.updated"] } ``````json theme={null} { "subscribed_events": ["transaction.created", "transaction.status.updated"] } ``````json theme={null} { "subscribed_events": [ "user.status.updated", "user.data.updated", "business.status.updated", "business.data.updated", "activity.created" ] } ```payload 예시와 서명 코드는 [webhook 가이드](https://docs.didit.me/ko/integration/webhooks.md)를 참고하세요. ## OpenAPI ````yaml ko/openapi-25.json POST /v3/webhook/destinations/ 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/: post: tags: - Webhook summary: webhook 대상 생성 description: >- webhook 대상을 생성합니다. 응답에는 자동 생성된 `secret_shared_key` HMAC 서명 비밀이 포함됩니다(나중에 `GET /v3/webhook/destinations/{destination_uuid}/`를 통해서도 읽을 수 있음). 항상 최소 하나의 이벤트가 포함된 `subscribed_events`를 전송하십시오(와일드카드 사용 불가). 빈 목록을 명시적으로 전달하면 400으로 거부되며, 필드를 생략하면 아무것도 구독하지 않는 대상이 생성되어 webhook을 수신할 수 없습니다. `(application, url)` 쌍은 애플리케이션의 대상 간에 고유해야 합니다. operationId: create_webhook_destination requestBody: required: true content: application/json: schema: type: object required: - label - url properties: label: type: string maxLength: 255 description: >- Console → Webhooks에 표시되는 사람이 읽기 쉬운 이름입니다. 여러 대상이 있을 때 대상을 구분하는 데 도움이 됩니다(예: "Prod", "Staging mirror"). url: type: string format: uri description: >- `POST` 요청을 수신할 HTTPS URL입니다. 애플리케이션의 대상 간에 고유해야 합니다. 안정적이고 보안이 강화된 endpoint를 사용하십시오. Didit은 백오프 일정에 따라 실패한 전송을 재시도합니다. maxLength: 2000 enabled: type: boolean default: true description: >- `false`인 경우 대상은 저장되지만 Didit은 해당 대상에 webhook을 푸시하지 않습니다. 보류해 두고자 하는 스테이징 구성에 유용합니다. webhook_version: type: string enum: - v1 - v2 - v3 description: >- Didit이 전송할 payload 스키마 버전입니다. `v3`가 현재 권장되는 형식이며, 이전 버전은 레거시 연동과의 하위 호환성을 위해 유지됩니다. subscribed_events: allOf: - $ref: '#/components/schemas/WebhookSubscribedEvents' description: >- 전송할 이벤트입니다. 사실상 필수 항목입니다. 명시적인 `[]`는 400 오류로 거부되며, 필드를 생략하면 구독이 없는 대상이 생성되어 아무것도 수신하지 않습니다. examples: session_updates: summary: 세션 상태 및 데이터 업데이트 value: label: Production session webhooks url: https://yourapp.com/webhooks/didit webhook_version: v3 subscribed_events: - status.updated - data.updated transaction_updates: summary: 거래 모니터링 업데이트 value: label: Transaction monitoring webhooks url: https://yourapp.com/webhooks/didit-transactions webhook_version: v3 subscribed_events: - transaction.created - transaction.status.updated entity_updates: summary: 사용자 및 기업 엔터티 업데이트 value: label: Entity lifecycle webhooks url: https://yourapp.com/webhooks/didit-entities webhook_version: v3 subscribed_events: - user.status.updated - user.data.updated - business.status.updated - business.data.updated - activity.created responses: '201': description: 대상이 생성되었습니다. `secret_shared_key`는 HMAC 서명 비밀입니다. 지금 저장하십시오. content: application/json: schema: type: object properties: uuid: type: string format: uuid description: 안정적인 대상 식별자입니다. 후속 호출에서 `{destination_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 description: >- 이 대상에 바인딩된 자동 생성 HMAC 서명 비밀(43자 URL 안전 token)입니다. 수신되는 webhook의 서명 헤더를 검증하는 데 사용합니다. API 키 호출자에게는 항상 전체가 반환됩니다. 콘솔 사용자는 `read:webhooks` 권한이 필요하며, 그렇지 않으면 빈 문자열이 표시됩니다. 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: Created: value: uuid: 11111111-2222-3333-4444-555555555555 label: Production session webhooks url: https://yourapp.com/webhooks/didit enabled: true 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-05-17T10:00:00Z' updated_at: '2026-05-17T10:00:00Z' health_status: healthy failing_streak: 0 failing_since: null last_success_at: null environment: live summary: total_deliveries: 0 failed_deliveries: 0 error_rate_percentage: 0 min_response_time_ms: null avg_response_time_ms: null max_response_time_ms: null last_delivery_at: null metrics_window_days: 30 '400': description: >- 검증 실패 — 일반적으로 중복된 URL, 누락되었거나 유효하지 않은 `subscribed_events`, 또는 알 수 없는 이벤트 이름 때문입니다. content: application/json: examples: Duplicate URL: value: url: - >- This webhook destination already exists for the application. Empty events list: value: subscribed_events: - At least one subscribed event is required. Unknown event: value: subscribed_events: - 'Unsupported webhook events: foo.bar' '403': description: >- API 키가 누락되었거나, 형식이 잘못되었거나, 만료되었거나, 다른 애플리케이션으로 범위가 지정되었습니다. 키가 누락된 경우 `403`을 반환하고, 잘못되었거나 취소되었거나 만료된 키는 `401`을 반환합니다. content: application/json: examples: Forbidden: value: detail: You do not have permission to perform this action. '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 POST 'https://verification.didit.me/v3/webhook/destinations/' \ -H 'x-api-key: YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "label": "Production session webhooks", "url": "https://yourapp.com/webhooks/didit", "webhook_version": "v3", "subscribed_events": ["status.updated", "data.updated"] }' - lang: python label: Python source: |- from didit import Didit # Reads DIDIT_API_KEY. client = Didit() result = client.webhooks.destinations.create( label="Production session webhooks", url="https://yourapp.com/webhooks/didit", webhook_version="v3", subscribed_events=["status.updated", "data.updated"], ) 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.create({ label: "Production session webhooks", url: "https://yourapp.com/webhooks/didit", webhook_version: "v3", subscribed_events: ["status.updated", "data.updated"], }); 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.Create(ctx, didit.WebhooksDestinationsCreateParams{\n\tLabel: \"Production session webhooks\",\n\tURL: \"https://yourapp.com/webhooks/didit\",\n\tWebhookVersion: didit.Some(didit.WebhooksDestinationsCreateParamsWebhookVersion(\"v3\")),\n\tSubscribedEvents: didit.Some([]didit.WebhookEvent{didit.WebhookEvent(\"status.updated\"), didit.WebhookEvent(\"data.updated\")}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" - lang: java label: Java source: >- import java.util.List; import me.didit.Didit; import me.didit.types.WebhookEvent; import me.didit.types.WebhooksDestinationsCreateParams; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.webhooks().destinations().create(WebhooksDestinationsCreateParams.builder() .label("Production session webhooks") .url("https://yourapp.com/webhooks/didit") .webhookVersion(WebhooksDestinationsCreateParams.WebhookVersion.of("v3")) .subscribedEvents(List.of(WebhookEvent.of("status.updated"), WebhookEvent.of("data.updated"))) .build()); System.out.println(result); - lang: php label: PHP source: |- webhooks->destinations->create([ 'label' => 'Production session webhooks', 'url' => 'https://yourapp.com/webhooks/didit', 'webhook_version' => 'v3', 'subscribed_events' => ['status.updated', 'data.updated'], ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.webhooks.destinations.create( label: "Production session webhooks", url: "https://yourapp.com/webhooks/didit", webhook_version: "v3", subscribed_events: ["status.updated", "data.updated"] ) 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.CreateAsync(new WebhooksDestinationsCreateParams { Label = "Production session webhooks", Url = "https://yourapp.com/webhooks/didit", WebhookVersion = new WebhooksDestinationsCreateParamsWebhookVersion("v3"), SubscribedEvents = new WebhookEvent[] { "status.updated", "data.updated" }, }); 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.