Webhook

웹훅이란?

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

웹훅 등록 방법

웹훅 등록을 위해 이벤트를 받을 webhook URL을 헬프데스크로 전달해 주세요.

웹훅 트리거

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"
  }