Didit은 상태가 바뀌어도 이메일을 보내지 않습니다. 웹훅을 설정하면 백엔드가 즉시 알 수 있으며, 처리 전에 반드시 서명을 검증하세요.
웹훅은 무언가 바뀔 때 Didit이 여러분의 URL로 보내는 HTTP 요청입니다. 개발자 → 웹훅에서 대상을 추가하고, 원하는 이벤트를 구독하세요 - 와일드카드는 없으므로 하나하나 나열해야 합니다 - 서명 시크릿을 저장하고, 처리하기 전에 반드시 서명을 검증하세요.
세션이 In Review나 Declined로 바뀌어도 Didit은 이메일을 보내지 않습니다. 콘솔을 새로고침하지 않고도 상태가 바뀐 순간을 알고 싶다면, 웹훅 - Didit이 자동으로 업데이트를 전달하는 여러분 서버의 URL - 을 설정하세요.
웹훅은 권장 연동 방식입니다. 결정 엔드포인트를 폴링하는 방법도 대체 수단으로는 작동하지만, 더 느리고 요청 수가 늘어나며, 오직 웹훅으로만 전달되는 이벤트 - 검토자의 데이터 수정, 트랜잭션 상태 변경, 엔티티 수준 변경 - 를 놓치게 됩니다.
#설정 방법
- 개발자 → 웹훅
해당 애플리케이션과 Live 또는 Sandbox 환경을 선택한 뒤 개발자와 웹훅을 여세요.
- 엔드포인트 추가
엔드포인트 추가를 누르고 HTTPS URL, 이름, 이벤트를 설정하세요. 이전 통합을 유지하는 경우 외에는 권장 v3를 사용하고 검토 후 확인하세요.
- 서명 시크릿 저장
각 엔드포인트에는 별도의 숨겨진 서명 비밀키가 있습니다. 표시를 누르고 본인 확인을 하면 보이며 60초 내에 다시 숨겨집니다. 서버 설정에 보관하세요. 표시가 비활성화되면 지원팀에 문의하세요. 개발자 → 웹훅.
- 테스트 이벤트 보내기
서명된 테스트 이벤트로 실제 인증 없이 엔드포인트, 서명과 처리를 확인하세요.
#구독할 수 있는 이벤트
와일드카드는 없습니다 - 원하는 모든 이벤트 계열을 나열해야 합니다. 여러 대상에 나눠 구독하는 것도 괜찮고, 종종 더 깔끔합니다.
| 이벤트 | 발생 시점 |
|---|---|
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 교환의 상태가 바뀔 때 |
session.status.updated나 kyc.completed라는 이벤트는 존재하지 않습니다. 이 목록에 없는 이름을 구독했다면 아무것도 받지 못하며, 겉으로는 전송 실패와 정확히 똑같아 보입니다. 먼저 이름을 확인하세요.
#엔드포인트가 해야 할 일
- 다른 무엇보다 먼저 서명을 검증하세요. 파싱된 JSON을 재직렬화한 것이 아니라 원본 요청 본문을 HMAC 처리하세요. 다시 문자열로 만들면 바이트가 바뀌어 서명이 맞지 않게 됩니다. 상수 시간 비교를 사용하세요.
- 빠르게 2xx를 반환하세요. 무거운 작업은 응답한 뒤 비동기로 처리하세요.
- 멱등성을 가지세요. 이벤트 ID나, 세션 ID + 상태 + 웹훅 타입 조합을 키로 사용하세요. 재시도와 중복은 실제로 일어납니다.
- 관심 있는 모든 상태를 처리하세요. 온보딩이 끝난 한참 뒤에 도착하는 상태도 포함됩니다 - 승인된 세션도 지속적인 AML 모니터링을 통해 이후 In Review로 바뀔 수 있습니다.
- HTTPS만 지원됩니다. 일반 HTTP 엔드포인트는 지원되지 않습니다.
#재시도
5xx 또는 404 응답에는 약 1분 후, 이어서 4분 후 두 번 재시도합니다. 5초 시간 초과나 연결 실패는 자동 재시도하지 않습니다. 수정 후 전달 목록에서 다시 보내세요. 최종 실패에는 알림이 표시됩니다.
모든 웹훅이 도착한다고 가정하지 마세요. 장애 후 재전송하거나 결과를 받지 못한 세션의 결정을 API로 조회하세요.
#방화벽이나 WAF 뒤에 있는 경우
Didit은 고정 IP 18.203.201.92에서 DiditWebhook/2.0 User-Agent로 전송합니다. 여러분의 엣지가 알 수 없는 클라이언트를 차단한다면 - Cloudflare의 기본 정책 등 - 수신 호스트명에 대해 해당 IP를 허용하세요. 그렇지 않으면 전송이 코드에 도달하기 전에 실패합니다.
#아직 백엔드가 없다면
백엔드를 구축하는 동안 콘솔의 Verifications 섹션에서 수동으로 결과를 확인하거나, 그동안 노코드 인증 링크를 사용할 수 있습니다.
#다음 단계
- 웹훅이 도착하지 않을 때: 웹훅이 오지 않을 때
- 도착한 각 상태가 의미하는 바 이해하기: 각 세션 상태가 의미하는 것
- 서명 검증 코드 샘플을 포함한 전체 기술 참고 자료: 웹훅
아직 해결되지 않았나요? 담당자와 이야기하세요.
조직 ID와 문의할 세션 ID를 함께 보내 주세요.