# 웹훅으로 인증 결과 받기

Source: https://help.didit.me/ko/integration/webhooks-basics
Updated: 2026-10-12

Didit은 상태가 바뀌어도 이메일을 보내지 않습니다. 웹훅을 설정하면 백엔드가 즉시 알 수 있으며, 처리 전에 반드시 서명을 검증하세요.

웹훅은 무언가 바뀔 때 Didit이 여러분의 URL로 보내는 HTTP 요청입니다. **개발자 → 웹훅**에서 대상을 추가하고, 원하는 이벤트를 구독하세요 - **와일드카드는 없으므로** 하나하나 나열해야 합니다 - 서명 시크릿을 저장하고, 처리하기 전에 반드시 서명을 검증하세요.

[Video: 웹훅 개요 - Didit Academy](https://www.youtube.com/watch?v=fX03-WEu_EI&t=192)

세션이 **In Review**나 **Declined**로 바뀌어도 Didit은 이메일을 보내지 않습니다. 콘솔을 새로고침하지 않고도 상태가 바뀐 순간을 알고 싶다면, 웹훅 - Didit이 자동으로 업데이트를 전달하는 여러분 서버의 URL - 을 설정하세요.

웹훅은 **권장** 연동 방식입니다. 결정 엔드포인트를 폴링하는 방법도 대체 수단으로는 작동하지만, 더 느리고 요청 수가 늘어나며, 오직 웹훅으로만 전달되는 이벤트 - 검토자의 데이터 수정, 트랜잭션 상태 변경, 엔티티 수준 변경 - 를 놓치게 됩니다.

## 설정 방법

1. **개발자 → 웹훅**

   해당 애플리케이션과 Live 또는 Sandbox 환경을 선택한 뒤 개발자와 웹훅을 여세요.

2. **엔드포인트 추가**

   엔드포인트 추가를 누르고 HTTPS URL, 이름, 이벤트를 설정하세요. 이전 통합을 유지하는 경우 외에는 권장 v3를 사용하고 검토 후 확인하세요.

3. **서명 시크릿 저장**

   각 엔드포인트에는 별도의 숨겨진 서명 비밀키가 있습니다. 표시를 누르고 본인 확인을 하면 보이며 60초 내에 다시 숨겨집니다. 서버 설정에 보관하세요. 표시가 비활성화되면 지원팀에 문의하세요. [개발자 → 웹훅](https://docs.didit.me/integration/webhooks#signature-verification).

4. **테스트 이벤트 보내기**

   서명된 테스트 이벤트로 실제 인증 없이 엔드포인트, 서명과 처리를 확인하세요.

![구독된 이벤트와 전송 이력이 있는 Didit 콘솔의 웹훅 대상](https://help.didit.me/screenshots/webhooks-light.webp)

*각 대상은 자체 구독 이벤트, 서명 시크릿, 전송 로그를 가집니다.*

## 구독할 수 있는 이벤트

**와일드카드는 없습니다** - 원하는 모든 이벤트 계열을 나열해야 합니다. 여러 대상에 나눠 구독하는 것도 괜찮고, 종종 더 깔끔합니다.

| 이벤트 | 발생 시점 |
|---|---|
| `status.updated` | KYC 또는 KYB 세션의 상태가 바뀔 때. 거의 확실히 필요한 이벤트 |
| `data.updated` | 생성 이후 인증 데이터가 수정될 때 - 검토자가 필드를 정정하는 경우 |
| `user.status.updated` | 통합 사용자가 ACTIVE, FLAGGED, BLOCKED 사이를 이동할 때 |
| `user.data.updated` | 통합 사용자의 프로필, 카운터, 식별자가 바뀔 때 |
| `business.status.updated` | 통합 사업체의 상태가 바뀔 때 |
| `business.data.updated` | 통합 사업체의 데이터가 바뀔 때 |
| `transaction.created` | 트랜잭션이 생성되고 초기 판정이 나올 때 |
| `transaction.status.updated` | 이후 트랜잭션의 상태가 바뀔 때 |
| `travel_rule.status.updated` | Travel Rule 교환의 상태가 바뀔 때 |

> **Note:** `session.status.updated`나 `kyc.completed`라는 이벤트는 존재하지 않습니다. 이 목록에 없는 이름을 구독했다면 아무것도 받지 못하며, 겉으로는 전송 실패와 정확히 똑같아 보입니다. 먼저 이름을 확인하세요.

## 엔드포인트가 해야 할 일

- **다른 무엇보다 먼저 서명을 검증하세요.** 파싱된 JSON을 재직렬화한 것이 아니라 **원본** 요청 본문을 HMAC 처리하세요. 다시 문자열로 만들면 바이트가 바뀌어 서명이 맞지 않게 됩니다. 상수 시간 비교를 사용하세요.
- **빠르게 2xx를 반환하세요.** 무거운 작업은 응답한 뒤 비동기로 처리하세요.
- **멱등성을 가지세요.** 이벤트 ID나, 세션 ID + 상태 + 웹훅 타입 조합을 키로 사용하세요. 재시도와 중복은 실제로 일어납니다.
- **관심 있는 모든 상태를 처리하세요.** 온보딩이 끝난 한참 뒤에 도착하는 상태도 포함됩니다 - 승인된 세션도 [지속적인 AML 모니터링](https://help.didit.me/ko/aml-screening/ongoing-monitoring)을 통해 이후 In Review로 바뀔 수 있습니다.
- **HTTPS만 지원됩니다.** 일반 HTTP 엔드포인트는 지원되지 않습니다.

## 재시도

5xx 또는 404 응답에는 약 1분 후, 이어서 4분 후 두 번 재시도합니다. 5초 시간 초과나 연결 실패는 자동 재시도하지 않습니다. 수정 후 전달 목록에서 다시 보내세요. 최종 실패에는 알림이 표시됩니다.

> **Warning:** 모든 웹훅이 도착한다고 가정하지 마세요. 장애 후 재전송하거나 결과를 받지 못한 세션의 결정을 API로 조회하세요.

## 방화벽이나 WAF 뒤에 있는 경우

Didit은 고정 IP **18.203.201.92**에서 `DiditWebhook/2.0` User-Agent로 전송합니다. 여러분의 엣지가 알 수 없는 클라이언트를 차단한다면 - Cloudflare의 기본 정책 등 - 수신 호스트명에 대해 해당 IP를 허용하세요. 그렇지 않으면 전송이 코드에 도달하기 전에 실패합니다.

## 아직 백엔드가 없다면

백엔드를 구축하는 동안 콘솔의 **Verifications** 섹션에서 수동으로 결과를 확인하거나, 그동안 [노코드 인증 링크](https://help.didit.me/ko/integration/integration-options)를 사용할 수 있습니다.

## 다음 단계

- 웹훅이 도착하지 않을 때: [웹훅이 오지 않을 때](https://help.didit.me/ko/integration/webhook-troubleshooting)
- 도착한 각 상태가 의미하는 바 이해하기: [각 세션 상태가 의미하는 것](https://help.didit.me/ko/verification-sessions/session-statuses)
- 서명 검증 코드 샘플을 포함한 전체 기술 참고 자료: [웹훅](https://docs.didit.me/integration/webhooks)