설정

Unico IDCloud에서 웹훅을 구성하려면 엔드포인트, 인증 방법, 재시도 정책을 제공하세요. 구성은 Unico 팀에서 수행합니다 — 웹훅을 등록하거나 업데이트하려면 CS / 온보딩 팀에 문의하세요.

필수 정보

필드	설명
알림 URL	Unico가 이벤트 알림을 전달하기 위해 호출할 엔드포인트. 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": "EVENT_TYPE_PROCESS_CREATED",
  "lastEventDescription": "Process created"
}

전체 페이로드 스키마와 lastEvent 값 목록은 이벤트 유형을 참조하세요.

예상 응답

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

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

빠르게 응답하세요

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

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