웹훅으로 인증 결과 받기
Didit은 인증 상태가 바뀌어도 이메일을 보내지 않습니다 - 웹훅을 설정하면 백엔드가 상황이 발생하는 즉시 알 수 있으며, 신뢰하기 전에 서명을 검증하세요.
웹훅은 무언가 바뀔 때 Didit이 여러분의 URL로 보내는 HTTP 요청입니다. API & Webhooks에서 대상을 추가하고, 원하는 이벤트를 구독하세요 - 와일드카드는 없으므로 하나하나 나열해야 합니다 - 서명 시크릿을 저장하고, 처리하기 전에 반드시 서명을 검증하세요.
세션이 In Review나 Declined로 바뀌어도 Didit은 이메일을 보내지 않습니다. 콘솔을 새로고침하지 않고도 상태가 바뀐 순간을 알고 싶다면, 웹훅 - Didit이 자동으로 업데이트를 전달하는 여러분 서버의 URL - 을 설정하세요.
웹훅은 권장 연동 방식입니다. 결정 엔드포인트를 폴링하는 방법도 대체 수단으로는 작동하지만, 더 느리고 요청 수가 늘어나며, 오직 웹훅으로만 전달되는 이벤트 - 검토자의 데이터 수정, 트랜잭션 상태 변경, 엔티티 수준 변경 - 를 놓치게 됩니다.
#설정 방법
- API & Webhooks로 이동
비즈니스 콘솔에서 이벤트를 받을 애플리케이션을 연 다음 API & Webhooks로 이동합니다.
- 대상 추가
레이블, 공개적으로 접근 가능한 HTTPS 엔드포인트 URL을 입력하고, 받고 싶은 이벤트를 선택합니다 - 최소한 세션 상태 변경은 포함하세요.
- 서명 시크릿 저장
대상은 시크릿을 한 번만 보여줍니다. 저장해 두세요 - 서버는 이 시크릿으로 요청이 실제로 Didit에서 왔는지, 사칭이 아닌지 확인합니다. 전체 검증 절차: 서명 검증.
- 테스트하기
같은 페이지에서 Try Webhook을 사용해 완전한 형태의 테스트 이벤트 - 승인, 거절, 검토 대기, KYB, 엔티티, 트랜잭션 시나리오 - 를 엔드포인트로 보내세요. 실제 인증을 실행하지 않고도 이 방법으로 연동을 검증할 수 있습니다.
- Add destination은 Didit이 결과를 게시할 URL을 등록합니다.
- 신뢰하기 전에 모든 전송을 이 서명 시크릿으로 검증하세요.
- 대상이 받을 이벤트를 선택하세요.
- Test Webhook은 엔드포인트가 이를 받아들이는지 확인할 수 있도록 샘플 페이로드를 전송합니다.
#구독할 수 있는 이벤트
와일드카드는 없습니다 - 원하는 모든 이벤트 계열을 나열해야 합니다. 여러 대상에 나눠 구독하는 것도 괜찮고, 종종 더 깔끔합니다.
| 이벤트 | 발생 시점 |
|---|---|
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, 타임아웃, 연결 실패 시 Didit은 두 번 재시도합니다.
- 첫 재시도는 최초 실패 후 약 1분 뒤
- 두 번째 재시도는 그 후 약 4분 뒤
그 이후에는 전송을 포기합니다. 모든 시도는 대상의 Deliveries 탭에 개별적으로 기록되므로, 추측하지 않고 정확히 무슨 일이 있었는지 확인할 수 있습니다.
5분에 걸친 두 번의 재시도는 견고한 큐가 아닙니다. 엔드포인트가 한 시간 동안 다운되어 있었다면 그 이벤트들은 사라집니다. 시작할 때 최종 상태를 알지 못하는 세션에 대해 결정 엔드포인트를 폴링해 재조정하세요 - 웹훅은 빠른 경로이지 유일한 경로가 아닙니다.
#방화벽이나 WAF 뒤에 있는 경우
Didit은 고정 IP 18.203.201.92에서 DiditWebhook/2.0 User-Agent로 전송합니다. 여러분의 엣지가 알 수 없는 클라이언트를 차단한다면 - Cloudflare의 기본 정책 등 - 수신 호스트명에 대해 해당 IP를 허용하세요. 그렇지 않으면 전송이 코드에 도달하기 전에 실패합니다.
#아직 백엔드가 없다면
백엔드를 구축하는 동안 콘솔의 Verifications 섹션에서 수동으로 결과를 확인하거나, 그동안 노코드 인증 링크를 사용할 수 있습니다.
#다음 단계
- 웹훅이 도착하지 않을 때: 웹훅이 오지 않을 때
- 도착한 각 상태가 의미하는 바 이해하기: 각 세션 상태가 의미하는 것
- 서명 검증 코드 샘플을 포함한 전체 기술 참고 자료: 웹훅