기업 확인(KYB) webhook API: 이벤트, 페이로드 및 서명

Didit의 KYB webhook은 기업 확인 세션의 상태가 변경되거나, 검토자 또는 법인 등기부가 데이터를 변경할 때 백엔드에 알려줍니다. 기업 엔티티에는 고유한 이벤트가 있습니다. webhook 대상 API 또는 Business Console에서 관심 있는 이벤트를 구독하십시오.

이벤트 목록

세션 이벤트는 사용자 세션과 기업 세션에 공통으로 사용됩니다. payload의 session_kind 필드는 해당 이벤트가 어떤 세션 유형을 가리키는지 알려줍니다. 엔티티 수준 이벤트는 세션 수준 이벤트와 별도로 제공됩니다.

세션 수준 이벤트

이벤트	발생 시점
`status.updated`	세션의 상태가 변경되었을 때입니다. 기업 확인(KYB) 세션의 경우 payload에 `session_kind: "business"`가 포함됩니다. 진행 상황을 추적하려면 이 이벤트를 사용하십시오.
`data.updated`	검토자가 법인 등기부 데이터를 수정했거나, 콘솔에서 주요 인물을 건너뛰거나 다시 생성했을 때, 또는 법인 등기부가 변경을 보고했을 때입니다(법인 등기부 모니터링을 사용할 수 있는 경우). `trigger` 필드가 원인을 알려줍니다.

지원자가 문서를 업로드하거나 주요 인물을 제출했을 때, 또는 AML 재검사가 완료되었을 때는 data.updated가 전송되지 않습니다. 이 진행 상황을 확인하려면 status.updated를 사용하거나 세션 결정 결과를 조회하십시오.

기업 엔티티 이벤트

이벤트	발생 시점
`business.status.updated`	연결된 기업 엔티티의 상태가 변경되었을 때입니다(`ACTIVE` / `FLAGGED` / `BLOCKED`).
`business.data.updated`	기업 엔티티의 프로필 필드 또는 집계 카운터가 변경되었을 때입니다.

webhook 대상에서 원하는 이벤트를 자유롭게 조합하여 구독할 수 있습니다. 기업 / 사용자 엔티티 이벤트의 전체 참조는 엔티티 webhook을 확인하십시오.

Payload 구조

세션 webhook은 data 래퍼 없이 평평한 payload를 사용합니다. 봉투 구조, 서명 헤더, 공통 필드는 모두 webhook 참조에 문서화되어 있습니다. KYB 세션에는 다음 필드가 추가로 포함됩니다.

필드	타입	설명
`session_kind`	`"business"`	범용 핸들러가 KYC와 KYB를 분기할 수 있게 합니다.
`business_session_id`	`uuid`	`session_id`와 같습니다.
`vendor_business_id`	string	세션 생성 시 제공한 경우, 기업 엔티티에 대한 고객사 식별자입니다.
`status`	string	정확한 상태 라벨입니다. 예를 들어 `"In Progress"`, `"Approved"`, `"Awaiting User"`가 있습니다. 상태를 참조하십시오.
`trigger`	string	선택 사항입니다. webhook이 전송된 이유입니다. KYB의 `data.updated`에서는 `"console_registry_edit"`, `"console_key_people_skip"`, `"console_key_people_regenerate"` 또는 `"kyb_registry_change"` 중 하나입니다.
`decision`	object	`status`가 `Approved`, `Declined`, `In Review` 또는 `Abandoned`일 때 포함됩니다. `GET /v3/session/{id}/decision/`와 같은 구조이며, 응답 스키마를 참조하십시오.
`resubmit_info`	object	`status`가 `Resubmitted`일 때 포함됩니다.

KYB 세션의 `status.updated`

{
  "event_id": "7f3c2c1e-6a1d-4c36-9d8e-0d3b5f4e2a10",
  "webhook_type": "status.updated",
  "session_id": "a1b2c3d4-5678-4abc-9def-1234567890ab",
  "business_session_id": "a1b2c3d4-5678-4abc-9def-1234567890ab",
  "session_kind": "business",
  "status": "Approved",
  "created_at": 1776515400,
  "timestamp": 1776515401,
  "application_id": "0c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
  "environment": "live",
  "workflow_id": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f7a8b9",
  "workflow_version": 3,
  "vendor_data": "biz-acme-001",
  "decision": { "...": "abbreviated KYB decision payload" }
}

decision 블록에는 registry_checks[], key_people_checks[], document_verifications[], aml_screenings[] 및 기타 KYB 배열이 포함됩니다.

KYB 세션의 `data.updated`

data.updated는 status.updated와 같은 평평한 구조를 가지며, 이벤트가 전송된 이유를 나타내는 trigger가 추가로 포함됩니다. 세션 상태가 Approved, Declined, In Review 또는 Abandoned이면 현재 decision도 함께 포함됩니다. 무엇이 바뀌었는지 확인하려면 결정 결과를 다시 조회하십시오. payload에는 changed_fields 목록이 없습니다.

`business.status.updated` 및 `business.data.updated`

엔티티 이벤트도 평평한 구조입니다. vendor_business_id, vendor_data, status(ACTIVE, FLAGGED 또는 BLOCKED), created_at이 포함됩니다. business.status.updated에는 previous_status가 추가로 포함됩니다. business.data.updated에는 changed_fields와 { field: { previous, current } } 형식의 changes 맵이 추가로 포함됩니다.

{
  "event_id": "2b9d6f0a-3c41-4e8b-b6a7-5d1e8f9a0c32",
  "webhook_type": "business.status.updated",
  "timestamp": 1776515401,
  "created_at": 1776515400,
  "application_id": "0c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
  "environment": "live",
  "vendor_business_id": "f7a9c1b2-4e6d-4f8a-9c5d-2a1b3c4d5e6f",
  "vendor_data": "biz-acme-001",
  "status": "FLAGGED",
  "previous_status": "ACTIVE"
}

서명 검증

모든 webhook은 webhook 대상의 공유 비밀을 사용하여 HMAC-SHA256으로 서명됩니다. 원본 요청 본문을 X-Signature-V2 헤더로 검증하십시오(권장). X-Timestamp가 300초보다 오래된 전송은 거부하십시오. 모든 서명 헤더, 서명 비밀 교체 시 겹치는 기간, 코드 샘플은 webhook 참조에 나와 있습니다.

재시도 정책

5xx 또는 404 응답, 시간 초과, 연결 실패가 발생하면 약 1분 후와 약 4분 후에 최대 2회까지 재시도하며, 그 후에도 실패하면 해당 전송은 버려집니다.
그 밖의 4xx 및 3xx 응답은 재시도하지 않습니다.
재시도할 때마다 event_id는 그대로 유지되므로, 이 값으로 중복을 제거하십시오.
webhook 대상의 전송 로그에서 전송을 다시 보낼 수 있습니다. 전체 정책은 webhook 참조에 있습니다.

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

status.updated 및 data.updated 이벤트에서 session_kind === "business"를 확인하여 기업 세션만 필터링하십시오.

다음 단계

Webhook 참조

대상, 서명, 재시도, 일반적인 패턴.

상태

세션 및 기능 상태 참조.

응답 스키마

KYB 결정 payload 해석 방법.

시작하기

기능

기업 프로필

레퍼런스

콘솔

기업 확인(KYB) webhook API: 이벤트, 페이로드 및 서명

이벤트 목록

세션 수준 이벤트

기업 엔티티 이벤트

Payload 구조

KYB 세션의 `status.updated`

KYB 세션의 `data.updated`

`business.status.updated` 및 `business.data.updated`

서명 검증

재시도 정책

구독하기

다음 단계

Webhook 참조

상태

응답 스키마

​이벤트 목록

​세션 수준 이벤트

​기업 엔티티 이벤트

​Payload 구조

​KYB 세션의 status.updated

​KYB 세션의 data.updated

​business.status.updated 및 business.data.updated

​서명 검증

​재시도 정책

​구독하기

​다음 단계

Webhook 참조

상태

응답 스키마

이벤트 목록

세션 수준 이벤트

기업 엔티티 이벤트

Payload 구조

KYB 세션의 `status.updated`

KYB 세션의 `data.updated`

`business.status.updated` 및 `business.data.updated`

서명 검증

재시도 정책

구독하기

다음 단계