Webhook

웹훅이란?

웹훅은 특정 이벤트가 발생한 경우 고객사 응용프로그램에게 이벤트에 대한 알림이 전달되는 기능을 의미합니다.

웹훅 등록 방법

1. 대시보드에 로그인 후 [설정] 메뉴로 이동합니다.

2. 좌측 사이드 메뉴에서 General 섹션의 Access Management 메뉴를 클릭합니다.

3. [웹훅 URL] 입력란에 원하는 웹훅 주소를 입력합니다.

4. 입력을 완료한 후 [저장] 버튼을 클릭합니다.

웹훅 트리거

Submission data는 입력받은 정보만 리턴합니다. 예를 들어 submission 제출 시 cf1, wallet address 등 optional 정보를 입력하지 않은 경우 해당 내용은 response에 포함되지 않습니다.

webhook_trigger	KYC Status	Description
submit	Pending	KYC 제출 완료되고, 자동처리되지 않아 수동 검수가 필요한 상태.
approved	Approved	KYC 승인
rejected	Rejected	KYC 거절
updated	-	KYC 정보가 변경됨
aml	Approved	AML스크리닝 결과
delete	-	KYC 제출건을 삭제했을 경우
injection	-	전달되는 웹훅의 타입

KYC Status Change

webhook_trigger 가 [approved, rejected, updated] 중 한 가지일 경우 아래 3가지 파라미터 추가 반환합니다.

• 단, submission 데이터에 해당 데이터가 존재하는 경우에 한 함 (gender, date_of_birth, nationality)

Key	Value	Description
webhook_trigger	submit, approved, rejected, updated	submit: KYC 제출 완료 후 'pending'상태 approved: KYC 제출과 동시에 자동으로 승인되었거나 pending인 KYC가 승인됨 rejected: KYC 제출과 동시에 자동으로 거절되었거나 pending인 KYC가 거절됨 updated: 제출된 KYC의 정보가 업데이트됨
kyc_result		KYC 제출 결과 오브젝트
kyc_result.status	approved / rejected	KYC 검수 결과
kyc_result.update_at	{update_at}	KYC 제출 상태가 approved 혹은 rejected로 변경 된 시점(UTC+0)
kyc_result.comment	{comment}	거절 사유에 대한 메세지 ※ webhook_trigger가 rejected일 때만전송 됨.
submission_id	{submission_id}	각 KYC 제출 건이 가지는 고유의 구분 값
applicant_id	{applicant_id}	중복 제출을 확인하기 위해 부여되는 고유 식별 ID로, KYC Status 가 Approved일 때만 전달 됩니다.
created_at	{create_at}	submission_id가 생성된 시점(UTC+0)
email	{email}	KYC 제출자의 이메일
userid	{userid}	고객사 고유의 KYC제출자 식별자 (≠ submission id)
cf	object	Step1 Input 데이터에 함께 제출한 cf1 ~ cf3 데이터 묶음 객체
cf.cf1	{cf1}	cf1 필드에 제출한 데이터
cf.cf2	{cf1}	cf2 필드에 제출한 데이터
cf.cf3	{cf3}	cf3 필드에 제출한 데이터
account_email	{account_email}	제출건 삭제를 시도한 어드민 계정
delete_time	{delete_time}	제출건 삭제 일시
comment	{comment}	제출건 삭제 시 남긴 코멘트
action		Injection 정보 객체
action.type	address	Injection 타입
action.created_at	{created_at}	Injection 실행 시각
gender	{gender}	제출된 사용자의 성별 (male 또는 female)
date_of_birth	{YYYY-MM-DD}	제출된 사용자의 생년월일 (YYYY-MM-DD 형식)
nationality	{nationality}	제출된 사용자의 국적 (3글자 형식의 국가코드 : ISO alpha3 형식)
tokenId	{tokenId}	Private mode 에서 live-form 으로 제출 시 사용한 tokenID

AML Results

KYC 승인 후 AML Screening 절차가 완료되면 AML 결과와 submission 정보가 리턴됩니다. KYC가 거절된 경우에는 AML Screening을 하지 않습니다. KYC가 승인된 경우에만 AML Screening을 하여 결과가 리턴됩니다.

Key	Value	Description	Required
webhook_trigger	aml	웹훅의 트리거 타입
submission_id	{submission_id}	각 KYC 제출 건이 가지는 고유의 구분 값
email	{email}	KYC 제출자의 이메일
userid	{userid}	고객사 고유의 KYC제출자 식별자 (≠ submission id)
aml_result		AML 결과 오브젝트
aml_result.currentstatus	Not Screened / Red Flag	AML 스크리닝 결과
aml_result.risk_level_summary	Not Screened/ HIGH/MEDIUM/LOW	AML 결과 레벨 값
cf	object	Step1 Input 데이터에 함께 제출한 cf1 ~ cf3 데이터 묶음 객체
cf.cf1	{cf1}	cf1 필드에 제출한 데이터
cf.cf2	{cf2}	cf2 필드에 제출한 데이터
cf.cf3	{cf3}	cf3 필드에 제출한 데이터
tokenId	{tokenId}	tokenId 제출 시 반환

Example

{
	"webhook_trigger":"aml",
	"submission_id":"string",
	"email":"[e-mail]",
	"userid":"test",
	"cf":{
		"cf1":"cf1",
		"cf2":"cf2",
		"cf3":"cf3"
	},
	"aml_result":{
		"currentstatus":"Not Screened",
		"risk_level_summary":"Not Screened"
	},
	"tokenId": "test"
}

---

Approved

Key	Value	Description	Required
webhook_trigger	approved	approved: KYC 제출과 동시에 자동으로 승인되었거나 pending인 KYC가 승인됨
kyc_result	object	KYC 제출 결과 오브젝트
kyc_result.status	{kyc_result.status}	KYC 검수 결과(approver or reject)
kyc_result.updated_at	{kyc_result.updated_at}	KYC 제출 상태가 approved 혹은 rejected로 변경 된 시점(UTC+0)
kyc_result.created_at	{kyc_result.created_at}	KYC가 제출된 날짜와 시간 (UTC+0)
kyc_result.kyc_result_at	{kyc_result.kyc_result_at}	KYC가 결과가 최초로 정해진 시간으로 approved/rejected 일 때만 출력 됨. (UTC+0)
kyc_result.pending_at	{kyc_result.pending_at}	KYC가 Pending으로 제출된 날짜와 시간 (UTC+0)
kyc_result.reviewer	{kyc_result.reviewer}	system: AI가 검수 agent: 사람이 검수
applicant_id	{applicant_id}	중복 제출을 확인하기 위해 부여되는 고유 식별 ID로, KYC Status 가 Approved일 때만 전달 됩니다.
submission_id	{submission_id}	각 KYC 제출 건이 가지는 고유의 구분 값
email	{email}	KYC 제출자의 이메일
tokenId	{tokenId}	Private mode 에서 live-form 으로 제출 시 사용한 tokenID
cf	object	Step1 Input 데이터에 함께 제출한 cf1 ~ cf3 데이터 묶음 객체
cf.cf1	{cf.cf1}	cf1 필드에 제출한 데이터
cf.cf2	{cf.cf2}	cf2 필드에 제출한 데이터
cf.cf3	{cf.cf3}	cf3 필드에 제출한 데이터
userid	{userid}	고객사 고유의 KYC제출자 식별자 (≠ submission id)
age_group	{age_group}	제출자의 연령대 (미성년자, 10대 초반, 청소년, 성인)
gender	{gender}	제출된 사용자의 성별 (male 또는 female)
date_of_birth	{date_of_birth}	제출된 사용자의 생년월일 (YYYY-MM-DD 형식)
nationality	{nationality}	제출된 사용자의 국적 (3글자 형식의 국가코드 : ISO alpha3 형식)
ipAddress	{ipAddress}	제출자의 IP 주소
fullName	{fullName}	제출자명
idType	{idType}	신분증 종류
issuingCountry	{issuingCountry}	발급 국가
issueDate	{issueDate}	발급 일자
expireDate	{expireDate}	만료 일자
identityNumber	{identityNumber}	주민등록번호
documentNumber	{documentNumber}	문서 고유번호 (여권번호, 해외 운전면허 번호 등)
addtional_list	[{addtional_list}]	대시보드에서 설정한 Additional form 에 대해, KYC 진행 시 사용자가 입력한 데이터 아래의 요청 타입의 경우 포함 특정 submissionId 또는 email 로 조회한 경우 ‘request_type’ 을 ‘others’ 로 조회한 경우
addtional_list.answer	{addtional_list.answer}	Additional form의 각 항목 명
addtional_list.inputValue	{addtional_list.inputValue}	각 항목에 대한 사용자 입력값
addtional_list.blockType	{addtional_list.blockType}	각 항목에 대한 데이터 타입

Example

{
    "webhook_trigger": "approved",
    "kyc_result": {
      "status": "string",
      "updated_at": "string",
      "created_at": "string",
      "kyc_result_at": "string",
      "pending_at" : "string",
      "reviewer": "string"
    },
    "applicant_id": "string",
    "submission_id": "string",
    "email": "string",
    "tokenId" : "string",
    "cf": {
      "cf1": "string",
      "cf2": "string",
      "cf3": "string"
    },
    "userid": "string",
    "age_group" : "string",
    "gender": "string",
    "date_of_birth": "string",
    "nationality": "string",
    "ipAddress": "string",
    "fullName": "string",
    "idType": "string",
    "issuingCountry": "string",
    "issueDate": "string",
    "expireDate": "string",
    "identityNumber" : "string",
    "documentNumber" : "string",
    "additional_list" : {
        "answer" : "string",
        "inputValue" : "string",
        "blockType" : "string"
    }
  }

---

Rejected

Key	Value	Description	Required
webhook_trigger	rejected	KYC 제출과 동시에 자동으로 거절되었거나 pending인 KYC가 거절됨
submission_id	{submission_id}	각 KYC 제출 건이 가지는 고유의 구분 값
applicant_id	{applicant_id}	중복 제출을 확인하기 위해 부여되는 고유 식별 ID로, KYC Status 가 Approved일 때만 전달 됩니다.
email	{email}	KYC 제출자의 이메일
kyc_result	object	KYC 제출 결과 오브젝트
kyc_result.status	{kyc_result.status}	KYC 검수 결과(approved/reject)
kyc_result.updated_at	{kyc_result.updated_at}	KYC 제출 상태가 approved 혹은 rejected로 변경 된 시점(UTC+0)
kyc_result.comment	[{kyc_result.comment	거절 사유
kyc_result.commentCode	{kyc_result.commentCode}	거절 사유 코드
cf	object	Step1 Input 데이터에 함께 제출한 cf1 ~ cf3 데이터 묶음 객체
cf.cf1	{cf.cf1}	cf1 필드에 제출한 데이터
cf.cf2	{cf.cf2}	cf2 필드에 제출한 데이터
cf.cf3	{cf.cf3}	cf3 필드에 제출한 데이터
userid	{userid}	고객사 고유의 KYC제출자 식별자 (≠ submission id)
tokenId	{tokenId}	Private mode 에서 live-form 으로 제출 시 사용한 tokenID
ipAddress	{ipAddress}	제출자의 IP 주소

Example

{
    "webhook_trigger": "rejected",
    "kyc_result": {
      "status": "string",
      "comment": "string",
      "updated_at": "string",
      "commentCode": "string"
    },
    "submission_id": "string",
    "applicant_id" : "string",
    "email": "string",
    "cf": {
      "cf1": "string",
      "cf2": "string",
      "cf3" : "string"
    },
    "userid": "string",
    "tokenId" : "string",
    "ipAddress": "string"
  }

---

Updated

Key	Value	Description	Required
webhook_trigger	updated	제출된 KYC의 정보가 업데이트됨
submission_id	{submission_id}	각 KYC 제출 건이 가지는 고유의 구분 값
email	{email}	KYC 제출자의 이메일
data	object	KYC 데이터 객체
data.update	[Array]	업데이트 된 필드 리스트
data.kyc_result	{data.kyc_result}	KYC 제출 결과
data.created_at	{data.created_at}	KYC가 제출된 날짜와 시간 (UTC+0)
data.kyc_result_at	{data.kyc_result_at}	KYC가 결과가 최초로 정해진 시간으로 approved/rejected 일 때만 출력 됨. (UTC+0)
data.pending_at	{data.pending_at}	KYC 제출 상태가 pending된 시점(UTC+0)
data.reviewer	{data.reviewer}	system: AI가 검수 agent: 사람이 검수
data.kyc_result	{data.kyc_result}	KYC 제출 결과
admin	{admin}	대시보드에서 업데이트한 관리자 이메일
update_time	{update_time}	대시보드에서 업데이트한 시간
userid	{userid}	고객사 고유의 KYC제출자 식별자 (≠ submission id)
tokenId	{tokenId}	Private mode 에서 live-form 으로 제출 시 사용한 tokenID
age_group	{age_group}	제출자의 연령대 (미성년자, 10대 초반, 청소년, 성인)
gender	{gender}	제출된 사용자의 성별 (male 또는 female)
date_of_birth	{date_of_birth}	제출된 사용자의 생년월일 (YYYY-MM-DD 형식)
nationality	{nationality}	제출된 사용자의 국적 (3글자 형식의 국가코드 : ISO alpha3 형식)
ipAddress	{ipAddress}	제출자의 IP 주소
fullName	{fullName}	제출자의 이름
idType	{idType}	신분증 종류
issuingCountry	{issuingCountry}	발급 국가
issueDate	{issueDate}	발급 일자
expireDate	{expireDate}	만료 일자
identityNumber	{identityNumber}	주민등록번호
documentNumber	{documentNumber}	문서고유번호
additional_list	[{addtional_list}]	대시보드에서 설정한 Additional form 에 대해, KYC 진행 시 사용자가 입력한 데이터 아래의 요청 타입의 경우 포함 특정 submissionId 또는 email 로 조회한 경우 ‘request_type’ 을 ‘others’ 로 조회한 경우
additional_list.answer	{additional_list.answer}	Additional form의 각 항목 명
additional_list.inputValue	{additional_list.inputValue}	각 항목에 대한 사용자 입력값
additional_list.blockType	{additional_list.blockType}	각 항목에 대한 데이터 타입

Example

{
	"webhook_trigger":"updated",
	"submission_id":"string",
	"email":"[e-mail]",
	"data":
	{
		"update":
			[
				"idType",
				"issuingCountry",
				"fullName",
				"gender",
				"birthDate",
				"nationality",
				"kycStatus",
				"issueDate",
				"identityNumber"
			],
		"kyc_result":"rejected"
	},
	"admin":"[e-mail]",
	"update_time":"2024-06-21T01:47:12.321Z",
	"age_group":"N/A",
	"gender":"female",
	"date_of_birth":"1999-10-19",
	"nationality":"KOR",
	"userid": "test",
	"tokenId": "test"
}

---

Submit

Key	Value	Description	Required
webhook_trigger	submit	submit: KYC 제출 완료 후 'pending'상태
submission_id	{submission_id}	각 KYC 제출 건이 가지는 고유의 구분 값
created_at	{created_at}	submission_id가 생성된 시점(UTC+0)
cf	object	Step1 Input 데이터에 함께 제출한 cf1 ~ cf3 데이터 묶음 객체
cf.cf1	{cf.cf1}	cf1 필드에 제출한 데이터
cf.cf2	{cf.cf2}	cf2 필드에 제출한 데이터
cf.cf3	{cf.cf3}	cf3 필드에 제출한 데이터
userid	{userid}	고객사 고유의 KYC제출자 식별자 (≠ submission id)
tokenId	{tokenId}	Private mode 에서 live-form 으로 제출 시 사용한 tokenID
ipAddress	{ipAddress}	제출자의 IP 주소
email	{email}	제출자의 이메일 주소

Example

{
    "webhook_trigger": "submit",
    "created_at": "string",
    "submission_id": "string",
    "email": "string",
    "cf": {
      "cf1": "string",
      "cf2": "string",
      "cf3": "string"
    },
    "userid": "string",
    "tokenid": "string",
    "ipAddress": "string"
  }

---

Delete

Name	Value	Description	Required
webhook_trigger	delete	전달되는 웹훅의 타입 delete: KYC 제출건을 삭제했을 경우
submission_id	{submission_id}	각 KYC 제출 건이 가지는 고유의 구분 값
account_email	{account_email}	제출건 삭제를 시도한 어드민 계정
delete_time	{delete_time}	제출건 삭제 일시
comment	{comment}	제출건 삭제 시 남긴 코멘트

Example

{
	"webhook_trigger":"delete",
	"submission_id":"string",
	"account_email":"[e-mail]",
	"delete_time":"2024-06-21T01:54:47.481Z",
	"comment":"test"
}

---

Injection

Name	Value	Description	Required
webhook_trigger	injection	전달되는 웹훅의 타입
action		Injection 정보 객체
action.type	address	Injection 타입
action.created_at	{created_at}	Injection 실행 시각
submission_id	{submission_id}	KYC 진행 시 발생한 고유 아이디 (submission_id)
email	{email}	KYC 진행 시 제출된 email
kyc_status	{kyc_status}	KYC 제출 결과
applicant_id	{applicant_id}	중복 제출을 확인하기 위해 부여되는 고유 식별 ID - KYC Status 가 Approved일 때만 전달 됩니다.
userid	{userid}	회사 내부에서 자체적으로 사용하는 사용자 ID, 기존 시스템 상에서 KYC를 제출한 사람이 어떤 사용자인지 확인하는 용도로 사용 됨. ※ 옵션으로 제공 되며 userid 매개변수를 포함해서 KYC를 제출하면 전송 됨.
cf1	{cf1}	cf1 필드에 제출한 데이터
cf2	{cf2}	cf2 필드에 제출한 데이터
cf3	{cf3}	cf3 필드에 제출한 데이터
tokenId	{tokenId}	tokenId 제출 시 반환

Example

{
	"webhook_trigger":"injection",
	"action":{
		"type":"address",
		"created_at":"2024-06-21T03:24:57.565Z"
	},
	"submission_id":"string",
	"email":"[e-mail]",
	"kyc_status":"approved",
	"applicant_id":"string",
	"cf1":"cf1",
	"cf2":"cf2",
	"cf3":"cf3",
	"userid":"test",
	"tokenId":"test"
}

---

샘플 데이터

submit

{
    uri: 'https://your-endPoint-url.com',
    method: 'POST',
    body: {
        webhook_trigger:"submit", 
        kyc_result:{
            status:"rejected",
            created_at:"2023-07-06T02:01:03.494Z"
         },
        submission_id:"{submissionId}",
        projectId:"{projectId}",
        email:"[e-mail]",
        userid:"{userid}"
    },
    json: true
}

approved

{
    uri: 'https://your-endPoint-url.com',
    method: 'POST',
    body: {
        webhook_trigger:"approved", 
        kyc_result:{
            status:"rejected",
            comment:"Multiple invalid KYC attempts"
            updated_at:"2023-07-06T00:45:05.738Z"
         },
        submission_id:"{submissionId}",
        projectId:"{projectId}",
        email:"[e-mail]",
        userid:"{userid}"
    },
    json: true
}

rejected

{
    uri: 'https://your-endPoint-url.com',
    method: 'POST',
    body: {
        webhook_trigger:"approved", 
        kyc_result:{
            status:"rejected",
            comment:"Multiple invalid KYC attempts"
            updated_at:"2023-07-06T00:45:05.738Z"
         },
        submission_id:"{submissionId}",
        projectId:"{projectId}",
        email:"[e-mail]",
        userid:"{userid}"
    },
    json: true
}

updated

{
  uri: 'https://your-endPoint-url.com',
  method: 'POST',
  body: {
    kyc_result: { status: 'approved', updated_at: '2023-07-11T09:13:24.751Z' },
    email: '[e-mail]',
    webhook_trigger: 'updated',
    submission_id: 'test_submissions_id',
    userid:{userid}
    
  },
  json: true
}

aml

{
    uri: 'https://your-endPoint-url.com',
    method: 'POST',
    body: {
         webhook_trigger: 'aml',
         submission_id: '{submissionId}',
         email: '[e-mail]',
         userid:{userid}
         aml_result: {
               currentstatus: 'Not Screened',
               risk_level_summary: 'Not Screened'
         }
   },
    json: true
}

Delete

{
    uri: 'https://your-endPoint-url.com',
    method: 'DEL',
    body: {
        webhook_trigger:"delete", 
        submission_id:"{submissionId}",
        account email:"[e-mail]",
        delete_time:"2024-05-03T02:01:03.494Z"
    },
    json: true
}

Injection

{
    uri: 'https://your-endPoint-url.com',
    method: 'PUT',
    body: {
        webhook_trigger:"injection", 
        action:{
            type:"address",
            created_at:"2024-05-03T02:01:03.494Z"
         },
        submission_id:"{submissionId}",
        email:"[e-mail]",
        userid:"{userid}"
    },
    json: true
}

---

암호화 옵션 사용 시 Output 의 양 방향 암/복호화

Output

• Body 에 암호화 된 결과 반환

  response : {
  		...
  		body : "encrypted-string"
  }