API 연동 기본 가이드 1 : Webhook (웹훅)
모두싸인 Webhook(웹훅)으로 모두싸인에서 발생하는 이벤트를 사용자가 지정한 특정 URL로 요청받을 수 있습니다.
Webhook(웹훅)이란, 서버에서 어떠한 작업이 수행 되었을 때 해당 작업이 수행되었음을 HTTP POST로 알리는 개념을 말합니다. 이에 따라 Webhook을 통해 모두싸인에서 발생하는 이벤트를 사용자가 지정한 특정 URL로 POST 요청받을 수 있습니다.
웹훅 이벤트 수신시 획득한 문서ID를 기반으로, API를 호출해 계약 상태값 변경 / 실시간 모니터링 / 데이터 작업 등을 진행할 수 있습니다.
구독 가능한 이벤트는 아래와 같습니다.
서명 시작 (document_started)
각 차례의 서명자 서명 완료 (document_signed)
모든 서명 완료(document_all_signed)
서명 요청 취소 (document_request_canceled) - 서명자의 서명 거절 (document_rejected)
서명자의 서명 취소 (document_signing_canceled)
모두싸인 로그인 후, 설정 > API 메뉴 > Webhook에서 Webhook을 신규 생성할 수 있습니다. API 기능이 포함된 요금제를 이용 중인 고객에 한해 제공됩니다. :
API 연동 및 웹훅 설정이 필요하신 경우, 문의하기를 눌러 폼을 제출해주시면 전문 컨설턴트가 자세한 안내를 도와드리겠습니다. (문의하기 >)
[Webhook 추가하기] 를 눌러 Webhook 이름 및 URL을 설정할 수 있습니다.
Webhook URL을 수정하거나 이벤트별로 구독 여부를 설정할 수 있습니다.
웹훅을 통해 다양한 작업을 진행할 수 있습니다.
아래 주요 이용 방법 외, 더 많은 웹훅 및 API 연동 이용 방법이 궁금하신 경우 문의하기를 눌러 폼을 제출해주시면 전문 컨설턴트가 자세한 안내를 도와드리겠습니다. (문의하기 >)
Slack(슬랙) 등 다른 툴로 실시간 이벤트 수신하기
웹훅 이벤트 수신시 획득한 문서ID를 가지고 이용중인 시스템에서 [문서 상세 조회 API]를 호출하여 슬랙으로 문서 ID를 포함한 상세 정보를 슬랙과 같은 기타 툴에서 이벤트 값을 받아볼 수 있습니다.
특정 설정값을 포함해 이벤트 수신하기 (커스텀 헤더)
이벤트 수신시 헤더에 특정 인증값이 있어야 접근이 가능하도록 사내 시스템이 설정된 경우 등 다양한 상황에 맞게 헤더를 설정해두시면 해당 설정값을 포함해서 웹훅 이벤트 수신을 받으실 수 있습니다.
문서 상세 정보를 사내 DB에 저장하여 계약 상태 업데이트 하기
웹훅 이벤트 수신시 획득한 문서 ID를 가지고 [문서 상세 조회 API]를 호출합니다. - 문서 상세 정보 API 리턴 바디에서 문서 상태, 거절 사 등을 확인할 수 있으며 이를 사내 DB에 저장하여 문서 상태값을 업데이트하거나 데이터 작업 등을 진행할 수 있습니다.
사내 시스템에서 완료된 계약 필터링 및 관리하기
웹훅을 통해 받은 이벤트를 기반으로 [문서 리스트 조회 API]를 호출해 진행 상태에 따른 계약 문서를 필터링하여 확인 및 관리할 수 있습니다.
200번대 응답이 아니거나 10초 이내에 응답이 오지 않을 경우, "호출 실패"로 판단하고 재시도 (총 5회)를 시도합니다.
웹훅 이벤트 수신 후, 내부 로직 수행시 10초 이상 지연 될 수 있다면, timeout으로 인해 재전송 될 수 있으니, 이벤트 수신 시 응답을(200번대 응답) 먼저 회신 후 내부 작업을 진행을 권장합니다.
사용하고 있던 요금제 중단시, 구독한 웹훅이 비활성화됩니다. 기존에 구독해두신 이벤트를 메모 해두어 새 요금제 시작 후, 설정 > API > Webhook에서 필요한 이벤트를 다시 활성화 부탁드립니다. (*웹훅 설정은 최고 관리자에 한해 가능합니다.)