메인 콘텐츠로 건너뛰기

설정

IDCloud는 통합 방식에 따라 두 가지 웹훅 모달리티를 지원합니다:

  • 포털 방식 — 웹 및 SDK 통합용. IDCloud 포털에서 직접 셀프서비스로 구성합니다.
  • 클라이언트별 방식 — Check 오케스트레이션 기능(비동기 플로우)을 사용하는 API 통합용. Unico 팀에서 구성합니다. 브라질 전용으로 제공됩니다.

웹훅 엔드포인트를 등록하거나 업데이트하려면 IDCloud 포털에 접속하여 설정 > 웹훅으로 이동하세요.

필수 정보​

필드설명
알림 URLUnico가 이벤트 알림을 전달하기 위해 호출할 엔드포인트. HTTPS로 접근 가능해야 합니다.
인증 유형Unico가 엔드포인트에 인증하는 방법. 아래 옵션을 참조하세요.
재시도 설정최대 시도 횟수 및 시도 간격(지수 백오프 적용).
동시성 제한최대 동시 처리 중인 전달 수(최대: 500).
타임아웃엔드포인트 응답의 최대 대기 시간(초).
알림할 상태알림을 트리거하는 프로세스 상태 집합. 현재 PROCESS_STATE_FINISHED로 고정되어 있으며, 현재는 구성할 수 없습니다.

인증 방법​

OAuth2

제공 사항:

  • 웹훅 endpoint
  • OAuth2 공급자 URL
  • OAuth2 공급자 ClientId
  • OAuth2 공급자 Secret

Unico는 클라이언트 자격 증명을 사용하여 공급자 URL에서 액세스 토큰을 요청하고 Bearer 토큰으로 엔드포인트에 전달합니다.

Basic Authorization

user:pass 형식으로 자격 증명을 제공하세요. Unico는 이를 Base64로 인코딩하여 모든 웹훅 호출의 Authorization: Basic <encoded> 헤더로 전송합니다.

API Key

두 가지 형식이 지원됩니다. 문자열은 첫 번째 콜론을 기준으로 분리됩니다:

  • header:value — 사용자 지정 헤더 이름을 설정합니다. 예시:
    • X-API-Key:abc123 → X-API-Key: abc123
    • Authorization:Bearer abc123 → Authorization: Bearer abc123
  • value만 (콜론 없음) — 값이 스킴 접두사 없이 Authorization 헤더로 전송됩니다. 예시: abc123 → Authorization: abc123.

Bearer 스킴이 필요한 경우 header:value 형식을 사용하세요 (예: Authorization:Bearer <token>); 값만 있는 형식은 접두사 없이 원시 값을 전송합니다.

인증 없음

자격 증명이 전송되지 않습니다. 개발 환경에서만 권장됩니다 — 프로덕션 엔드포인트는 항상 인증을 요구해야 합니다.

알림을 트리거하는 프로세스 상태​

현재 Unico는 프로세스가 다음 상태로 전환될 때마다 알림을 보냅니다:

상태설명
PROCESS_STATE_FINISHED프로세스 완료 — 결과에 관계없이 최종 상태.
상태는 변경될 수 있습니다

플랫폼에서 알림하는 상태 집합은 향후 변경될 수 있습니다. 엔드포인트가 반응하는 상태를 구성 가능하게 만들어 새 상태를 추가할 때 서비스를 재배포하지 않아도 되도록 하세요.

요청 형식​

웹훅 전달은 엔드포인트에 대한 POST 요청입니다. 본문에는 프로세스 식별자와 현재 상태가 포함됩니다.

{
  "processId": "8263a268-5388-492a-bca2-28e1ff4a69f0",
  "state": "PROCESS_STATE_FINISHED",
  "flow": "id"
}
lastEvent 및 lastEventDescription

이 두 필드는 result = expired인 경우, 즉 사용자가 여정을 완료하기 전에 프로세스가 만료된 경우에만 페이로드에 나타납니다. 정상 완료 페이로드에서는 존재하지 않습니다. 전체 스키마와 가능한 lastEvent 값 목록은 이벤트 유형을 참조하세요.

예상 응답​

엔드포인트는 동기적으로 응답해야 합니다:

  • 성공: 200–299 범위의 모든 HTTP 상태.
  • 실패: 다른 모든 상태. Unico는 구성된 최대 시도 횟수에 도달하거나 2xx를 받을 때까지 지수 백오프로 재시도합니다.
빠르게 응답하세요

구성된 타임아웃 이내에 웹훅을 빠르게 확인하고 페이로드를 자체적으로 비동기 처리하세요. 웹훅 핸들러 내에서 장시간 처리하면 타임아웃 및 불필요한 재시도가 발생할 가능성이 높아집니다.

멱등성 및 재시도 처리 지침은 보안을 참조하세요.

마지막 업데이트 에