메인 콘텐츠로 건너뛰기

웹훅

이 문서의 GetProcess 관련 문서들은 엔드포인트를 호출하여 프로세스의 상태를 가져오는 방법을 설명합니다. 이 방식은 생성된 프로세스에 대한 정보를 받기 위해 폴링을 수행하는 것입니다. 즉, 동일한 프로세스에 대해 최신 상태를 가져오기 위해 엔드포인트를 여러 번 호출할 수 있습니다.

웹훅을 사용하면 프로세스의 상태가 변경될 때마다 특정 엔드포인트에 알릴 수 있습니다.

웹훅이란 무엇인가요?​

웹훅은 시스템 간의 비동기 통합을 가능하게 하는 시스템 알림 서비스로, 한 시스템이 트리거를 통해 다른 시스템에 알립니다. 이를 통해 웹훅은 업데이트를 확인하기 위한 지속적인 폴링 없이도 시스템을 최신 정보로 유지할 수 있습니다.

웹훅 설정 방법​

웹훅을 설정하려면 다음 정보가 필요합니다:

  • 알림 URL: Unico가 상태 업데이트에 대한 알림을 보내는 데 사용하는 엔드포인트입니다.
  • 인증 유형: 엔드포인트 호출을 인증하는 데 사용되는 방식입니다. 다음 옵션을 사용할 수 있습니다:
    • OAuth2;
    • Basic Authorization;
    • API Key;
    • 인증 없음.
  • OAuth2의 경우, 다음 정보를 제공해야 합니다:
    • 웹훅 endpoint;
    • OAuth2 제공자 URL;
    • OAuth2 제공자 ClientId;
    • OAuth2 제공자 Secret.
  • Basic Authorization의 경우, user:pass 형식으로 전송해야 합니다.
  • API Key의 경우, 두 가지 형식이 가능합니다:
    • 특정 헤더 이름을 지정하고자 할 때는 header:value;
    • 원하는 헤더가 Authorization일 때는 value.
  • 재시도 설정: 엔드포인트 호출이 실패할 경우의 시도 횟수를 나타냅니다:
    • 최대 시도 횟수;
    • 시도 간격(초 단위);
    • 요청 제한(Rate Limit): 동시 전송 가능한 최대 횟수(최대: 500);
    • 타임아웃: 엔드포인트 응답을 기다리는 최대 시간(초 단위).
  • 알림받을 상태: 알림을 받고 싶은 특정 상태를 구독할 수 있습니다. 다음이 포함됩니다:
    • approved: 거래 승인됨;
    • processing: 거래 처리 중;
    • inconclusive: 결정적인 검증을 수행할 수 없음;
    • shared: 거래가 공유되어 제출 대기 중;
    • skipped: 사용자가 흐름에서 생체 인식 캡처를 건너뜀;
    • unknown-share: 사용자가 구매를 인식하지 못한다고 표시함;
    • absent-holder: 카드 소유자가 캡처를 수행하기 위해 자리에 없음;
    • expired: 사용자가 지정된 시간 내에 캡처를 완료하지 못해 거래가 만료됨.
인증에 관하여

API는 Basic Authentication 또는 API Key와 같은 인증 방식으로 보호될 수 있습니다. 추가적인 보호를 위해 접근이 허용된 유효한 IP 목록도 정의할 수 있습니다.

비대면 카드 검증과의 통합​

플랫폼에서 웹훅을 설정하면, 귀사가 이러한 업데이트를 수신하기 위해 개발한 API의 엔드포인트로 전송되는 알림을 통해 프로세스에 대한 정보를 받을 수 있습니다.

플랫폼이 API로 전송하는 정보는 다음을 포함합니다:

  • ID: 거래 ID;
  • Status: 거래 상태;
  • HasIdentityChanged: 거래에서 신원 변경이 발생했는지 여부(선택 사항).
참고

웹훅 설정을 통해 클라이언트가 알림받고 싶은 상태를 선택할 수 있다는 점에 유의하세요. 이 정보를 전송한 후, 예상되는 응답은 동기식이어야 합니다.

요청​

요청은 정보를 더 쉽고 안전하게 전송할 수 있도록 REST API에 대한 POST 메서드여야 합니다. 모든 필드는 필수여야 합니다. 요청 본문은 다음 예시와 같이 거래 ID와 상태를 받아야 합니다:

{
  "id": "8263a268-5388-492a-bca2-28e1ff4a69f0",
  "status": "approved",
  "hasIdentityChanged": false
}

응답​

응답은 동기식이어야 합니다. 성공한 요청의 상태는 200에서 299 사이여야 합니다. 그 외의 상태는 실패로 간주되며, 비대면 카드 검증은 2xx 응답을 받거나 최대 시도 횟수에 도달할 때까지 추가 알림 시도(시도 사이에 지수 백오프 적용)를 진행합니다.

응답 상태​

현재 저희는 일련의 상태들을 보유하고 있지만, 이 목록은 향후 변경될 수 있습니다. 따라서 클라이언트가 관심 있는 상태에 대해 조치를 취할 수 있도록 설정 가능하게 만드는 것이 권장됩니다. 예를 들어, 캡처가 성공적으로 완료될 때마다 조치를 취하려는 경우, 현재는 "processing" 상태에서 이 일이 발생합니다. 하지만 이는 향후 변경될 수 있으므로, 성공적인 캡처를 나타내는 상태를 시스템에서 설정 가능하게 만들어, 향후 "captured" 상태로 변경되더라도 쉽게 반영할 수 있도록 하는 것이 좋습니다.

또한, 특정 상태에 대한 구체적인 조치와 인식되지 않은 상태에 대한 일반적인 조치를 함께 마련하는 것을 권장합니다(예: "processing"과 "approved"가 아닌 모든 것을 결정 불가로 간주). 이는 향후 새로운 상태가 나타날 수 있으며, 이로 인해 웹훅이 중단되지 않아야 하기 때문에 중요합니다.

중요 고려 사항​

비대면 카드 검증이 상태 변경을 알리기 위해 사용할 API를 개발할 때는 다음 사항에 유의하세요:

요청 제한(Rate limit) — 거래가 많은 상황에서 리소스에 과부하가 걸리지 않도록, 엔드포인트가 호출될 수 있는 횟수에 상한선을 지정할 수 있습니다.

오류율(Error Rate) — 오류율([200, 299] 범위를 벗어난 응답)은 항상 낮게 유지되어야 합니다. 그렇지 않으면 웹훅 처리량이 자동으로 감소하며, 이 감소가 재시도 메커니즘과 결합되어 새로운 웹훅의 실행 시간이 늘어날 수 있습니다.

멱등성(Idempotence) — 현재 웹훅 구현은 최소 1회 전달(at-least-once delivery)을 보장하므로, 동일한 상태가 두 번 이상 알림될 수 있습니다. 따라서 엔드포인트 구현은 멱등성을 갖도록 이루어져야 합니다.

폴백(Fallback) — 웹훅 서비스가 이용 불가능한 경우를 대비하여, 설정된 응답 시간 내에 거래 상태를 계속 조회할 수 있도록 폴백 방법을 마련하는 것이 권장됩니다. 엔드포인트 조회는 이 문서의 API 레퍼런스 섹션에 설명되어 있습니다.

마지막 업데이트 에