> ## 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.

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

> Didit의 KYB webhook 이벤트: 세션과 기업 엔티티의 트리거, 페이로드 스키마, HMAC 서명 검증. 인증 건당 $2.00부터, 계약 불필요.

Didit의 KYB webhook은 기업 확인 세션의 상태가 변경되거나, 검토자 또는 법인 등기부가 데이터를 변경할 때 백엔드에 알려줍니다.
기업 엔티티에는 고유한 이벤트가 있습니다.
[webhook 대상 API](https://docs.didit.me/ko/management-api/webhook/list-destinations.md) 또는 Business Console에서 관심 있는 이벤트를 구독하십시오.

## 이벤트 목록

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

### 세션 수준 이벤트

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

지원자가 문서를 업로드하거나 주요 인물을 제출했을 때, 또는 AML 재검사가 완료되었을 때는 `data.updated`가 전송되지 않습니다.
이 진행 상황을 확인하려면 `status.updated`를 사용하거나 [세션 결정 결과를 조회](https://docs.didit.me/ko/sessions-api/retrieve-session.md)하십시오.

### 기업 엔티티 이벤트

| 이벤트 | 발생 시점 |
| - | - |
| `business.status.updated` | 연결된 [기업 엔티티](https://docs.didit.me/ko/entities/businesses/overview.md)의 상태가 변경되었을 때입니다(`ACTIVE` / `FLAGGED` / `BLOCKED`). |
| `business.data.updated` | 기업 엔티티의 프로필 필드 또는 집계 카운터가 변경되었을 때입니다. |

webhook 대상에서 원하는 이벤트를 자유롭게 조합하여 구독할 수 있습니다.
기업 / 사용자 엔티티 이벤트의 전체 참조는 [엔티티 webhook](https://docs.didit.me/ko/entities/webhooks.md)을 확인하십시오.

## Payload 구조

세션 webhook은 `data` 래퍼 없이 평평한 payload를 사용합니다.
봉투 구조, 서명 헤더, 공통 필드는 모두 [webhook 참조](https://docs.didit.me/ko/integration/webhooks.md#payload-구조)에 문서화되어 있습니다.
KYB 세션에는 다음 필드가 추가로 포함됩니다.

| 필드 | 타입 | 설명 |
| - | - | - |
| `session_kind` | `"business"` | 범용 핸들러가 KYC와 KYB를 분기할 수 있게 합니다. |
| `business_session_id` | `uuid` | `session_id`와 같습니다. |
| `vendor_business_id` | string | 세션 생성 시 제공한 경우, 기업 엔티티에 대한 고객사 식별자입니다. |
| `status` | string | 정확한 상태 라벨입니다. 예를 들어 `"In Progress"`, `"Approved"`, `"Awaiting User"`가 있습니다. [상태](https://docs.didit.me/ko/business-verification/statuses.md)를 참조하십시오. |
| `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/`](https://docs.didit.me/ko/sessions-api/retrieve-session)와 같은 구조이며, [응답 스키마](https://docs.didit.me/ko/business-verification/response-schema.md)를 참조하십시오. |
| `resubmit_info` | object | `status`가 `Resubmitted`일 때 포함됩니다. |

### KYB 세션의 `status.updated`

```json theme={null}
{
  "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` 맵이 추가로 포함됩니다.

```json theme={null}
{
  "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 참조](https://docs.didit.me/ko/integration/webhooks.md#서명-검증)에 나와 있습니다.

## 재시도 정책

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

## 구독하기

[webhook 대상](https://docs.didit.me/ko/management-api/webhook/create-destination.md)에서 필요한 이벤트를 구독하십시오.

```bash theme={null}
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"`를 확인하여 기업 세션만 필터링하십시오.

## 다음 단계

> [card] [Webhook 참조](https://docs.didit.me/ko/integration/webhooks.md)
>
> 대상, 서명, 재시도, 일반적인 패턴.

> [card] [상태](https://docs.didit.me/ko/business-verification/statuses.md)
>
> 세션 및 기능 상태 참조.

> [card] [응답 스키마](https://docs.didit.me/ko/business-verification/response-schema.md)
>
> KYB 결정 payload 해석 방법.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.