Webhook 설정
현재 사용 중인 워크스페이스에서 소유한 문서와 관련되어 발생하는 이벤트를 이용자가 지정한 URL로 POST 요청으로 받을 수 있습니다.
- 서명 요청자로서 서명을 요청한 문서와 관련되어 발생하는 이벤트를 전달 받습니다.
- 참여자로서 서명할 문서와 관련되어 발생하는 이벤트를 전달 받습니다.
사용하지 않는 웹훅 삭제모니터링을 통해 지속적으로 실패 요청이 발생하는 웹훅에 대해 예고없이 웹훅 이벤트 비활성화 또는 웹훅 삭제를 수행합니다. 이점 유의 하시기 바라며, 사용하지 않는 웹훅은 이벤트를 꺼두거나 삭제를 권장 드립니다.
웹훅 추가
워크스페이스 최고 관리자는 모두싸인 웹의 통합 설정 > 워크스페이스 관리 > API 연동 > 웹훅 메뉴에서 웹훅을 추가할 수 있습니다. 웹훅 목록에는 웹훅마다 이름, 웹훅 URL, 구독 중인 이벤트 개수가 보입니다.
웹훅 추가하기 버튼을 눌러 웹훅 추가 창을 엽니다.
웹훅 추가 창에서 웹훅 URL과 이름을 입력하고 추가하기를 누릅니다. 이름은 100자까지 입력할 수 있습니다.
- 웹훅 URL은 https 주소만 사용할 수 있습니다.
웹훅 URL 입력 시 HTTPS 프로토콜 필수웹훅을 등록할 때 입력하는 URL은 공개적으로 접근 가능한 HTTPS 주소여야 하며,
인증 기관(CA)에서 발급된 유효한 인증서가 설정되어 있어야 합니다.🚫 localhost, 127.0.0.1 등 로컬 주소는 웹훅에서 직접 사용할 수 없습니다.
웹훅은 외부에서 해당 URL로 요청을 보내는 구조이기 때문에, 로컬 환경에서는 접근이 불가능합니다.✅ 테스트를 위해 다음과 같은 터널링 서비스를 사용할 수 있습니다:
위 도구를 사용하면 로컬 서버를 외부에서 접근 가능한 HTTPS URL로 프록싱할 수 있습니다.
리다이렉트 없는 최종 주소를 등록해 주세요웹훅 요청이 리다이렉트 응답을 받으면 모두싸인은 리다이렉트를 따라가 최종 주소의 응답으로 성공과 실패를 판단합니다. 이때 301, 302, 303 리다이렉트에서는 요청이
GET으로 바뀌어 본문이 전달되지 않습니다. 리다이렉트를 여러 번 거치면 실패할 수도 있습니다.웹훅 URL에는 리다이렉트 없이 바로 2xx로 응답하는 최종 주소를 등록해 주세요.
웹훅 상세 화면
목록에서 웹훅을 선택하면 웹훅 상세 화면이 열립니다. 상세 화면은 세 개의 탭으로 나뉘어 있습니다.
| 탭 | 할 수 있는 일 |
|---|---|
| 웹훅 설정 | 웹훅 URL·이름·커스텀 헤더를 확인하고 수정합니다. 웹훅 테스트를 보내거나 웹훅을 삭제할 수 있습니다. |
| 구독 이벤트 | 받을 이벤트를 켜고 끕니다. |
| 전송 이력 | 최근 30일 동안 이 웹훅의 전송 결과를 확인하고, 받지 못한 이벤트를 다시 보냅니다. |
웹훅 설정
웹훅 정보에서 저장된 웹훅 URL, 이름, 커스텀 헤더를 확인할 수 있습니다. 웹훅 허용 정책이 등록된 웹훅은 그 아래에 허용 이메일 주소가 함께 보입니다.
수정하기를 누르면 웹훅 URL, 이름, 커스텀 헤더를 함께 고칠 수 있습니다. 저장하기를 누르면 세 항목이 한 번에 저장되고, 저장에 실패하면 세 항목 모두 수정 전 값으로 남습니다.
웹훅 삭제에서 삭제하기를 누르면 웹훅이 삭제됩니다. 이 웹훅의 전송 이력도 함께 삭제됩니다.
커스텀 헤더
커스텀 헤더를 등록하면 모든 웹훅 요청에 함께 실립니다. 수신 서버에서 요청을 확인하는 인증 토큰 등을 등록할 때 사용할 수 있습니다. 헤더 이름은 200자, 값은 500자까지 입력할 수 있습니다.
아래 헤더 이름은 모두싸인이 모든 웹훅 요청에 직접 싣기 때문에 등록할 수 없습니다. 대소문자와 이름 앞뒤 공백은 구분하지 않습니다.
Modusign-Webhook-IdModusign-Delivery-IdModusign-Delivery-AttemptModusign-Timestamp
이 이름으로 헤더를 등록하거나, 다른 헤더의 이름을 이 이름으로 바꾸면 저장되지 않습니다. API로 웹훅을 생성하거나 수정할 때에는 400 Bad Request와 title Webhook header name is reserved가 반환됩니다.
이미 등록되어 있던 헤더이 이름의 헤더가 이미 등록된 웹훅은 그대로 사용할 수 있습니다. 해당 헤더는 요청에 실리지 않고 모두싸인 값이 실립니다. 헤더 값을 바꾸면 저장되지 않으니, 필요하지 않다면 해당 헤더를 삭제해 주세요.
User-Agent 헤더는 등록할 수 있습니다. 등록하면 모두싸인 기본값 Modusign-Webhook 대신 등록한 값이 실립니다. 각 헤더의 값은 Webhook event의 요청 헤더 절을 확인해 주세요.
구독 이벤트
구독 이벤트 탭에서 받을 이벤트를 켜고 끌 수 있습니다. 켜거나 끄는 즉시 저장되며, 오른쪽 위에 구독 중인 이벤트 개수가 보입니다. 이벤트별 발생 조건과 본문은 Webhook event를 확인해 주세요.
전송 이력
전송 이력 탭에서는 최근 30일 동안 이 웹훅의 전송 결과를 확인하고, 받지 못한 이벤트를 다시 보낼 수 있습니다. 자세한 내용은 웹훅 전송 이력 확인하기를 확인해 주세요.
웹훅 테스트
웹훅을 추가한 뒤 실제 문서 이벤트가 생기기 전에, 수신 서버가 모두싸인의 요청을 받는지 미리 확인할 수 있습니다. 웹훅 테스트는 저장된 웹훅 URL과 커스텀 헤더로 선택한 이벤트의 예시 데이터를 보내고, 수신 서버의 응답을 바로 보여 줍니다.
테스트 보내기
- 웹훅 상세 화면의
웹훅 설정탭에서웹훅 테스트를 누릅니다. - 오른쪽에 열린 창에서 보낼 이벤트를 하나 고릅니다. 구독하지 않은 이벤트도 고를 수 있습니다.
요청에서 보낼 요청을 확인합니다. 웹훅 URL, 헤더, 본문이 보이며,본문 복사나curl 복사로 복사할 수 있습니다.보내기를 누르고응답에서 결과를 확인합니다.
보내는 요청
| 항목 | 내용 |
|---|---|
| 웹훅 URL·커스텀 헤더 | 웹훅에 저장된 값으로 보냅니다. 수정하고 저장하지 않은 값은 쓰지 않으므로, 바꾼 값으로 테스트하려면 먼저 저장해 주세요. |
| 모두싸인 헤더 | 실제 전송과 같은 Modusign-Webhook-Id, Modusign-Delivery-Id, Modusign-Delivery-Attempt, Modusign-Timestamp, User-Agent, Content-Type 헤더가 실립니다. Modusign-Delivery-Id는 테스트마다 새로 정해지고, Modusign-Delivery-Attempt는 1입니다. 요청에 보이는 Modusign-Delivery-Id와 Modusign-Timestamp는 실제로 보낼 때 새 값으로 바뀝니다. |
| 본문 | 선택한 이벤트의 예시 데이터를 실제 전송과 같은 형식으로 보냅니다. 문서 ID는 실제 문서가 아닌 고정된 예시 값이고, 서명 요청자 이메일은 테스트를 보낸 최고 관리자의 이메일입니다. |
결과 확인하기
응답에 시도 일시, 응답 결과, 소요 시간이 보입니다. 수신 서버는 10초 안에 응답해야 하며, 2xx로 응답하면 성공입니다. 실패하면 실패 원인과 사유가 함께 보입니다.
| 결과 | 의미 |
|---|---|
| 성공 | 수신 서버가 10초 안에 2xx로 응답했습니다. 성공 200처럼 응답 상태 코드가 함께 보입니다. |
| 수신 서버가 거부 | 수신 서버가 2xx가 아닌 응답을 돌려주었습니다. 실패 401 인증 실패처럼 응답 상태 코드와 사유가 보입니다. |
| 10초 안에 응답 없음 | 수신 서버가 10초 안에 응답하지 않았습니다. |
| 연결하지 못함 | 수신 서버에 연결하지 못했습니다. 인증서 문제로 연결하지 못했다면 인증서 오류가 보입니다. |
수신 서버의 응답 본문과 응답 헤더는 보이지 않습니다. 실패 원인별로 확인할 곳은 웹훅 전송 이력 확인하기의 실패 원인 확인하기를 참고해 주세요. 원인을 고쳐 저장한 뒤 다시 테스트하면 됩니다.
테스트 요청을 처리할 때 확인하세요
- 수신 서버는 헤더로 웹훅 테스트와 실제 전송을 구분할 수 없습니다. 테스트 요청으로 실제 업무가 처리되지 않도록 주의해 주세요.
- 본문의 문서 ID로 모두싸인 문서를 조회하면 문서를 찾을 수 없습니다.
- 같은 문서 ID를 중복으로 거르는 수신 서버는 두 번째 테스트부터 요청을 무시할 수 있습니다.
요청에는 커스텀 헤더 값이 가려지지 않고 그대로 보입니다. 화면을 공유하거나 캡처할 때 주의해 주세요.
웹훅 테스트 이용 안내
- 웹훅 테스트는 전송 이력에 남지 않으며, 재전송이나 자동 재시도 대상이 아닙니다.
- 구독 이벤트 설정과 웹훅 허용 정책은 웹훅 테스트에 적용되지 않습니다.
- 웹훅을 추가한 뒤 웹훅 상세 화면에서만 보낼 수 있습니다. 테스트에 실패해도 웹훅 저장에는 영향이 없습니다.
- 모바일 웹에서는 웹훅 테스트를 제공하지 않습니다.
- 워크스페이스에서 웹훅 기능을 이용할 수 없으면 웹훅 테스트를 보낼 수 없습니다. 이때는 구독 상태와 요금제를 확인해 주세요.
자주 묻는 질문
웹훅 테스트는 성공했는데 실제 웹훅이 오지 않습니다.
웹훅 테스트에는 구독 이벤트 설정과 웹훅 허용 정책이 적용되지 않습니다. 아래를 확인해 주세요.
구독 이벤트탭에서 받으려는 이벤트가 켜져 있는지 확인합니다.- 웹훅 허용 정책을 등록했다면, 서명을 요청한 이용자의 이메일이 허용 정책에 막혀 있지 않은지 확인합니다.
전송 이력탭에서 그 문서 ID로 검색해 모두싸인이 보냈는지, 수신 서버가 어떻게 응답했는지 확인합니다.
웹훅 테스트 결과를 전송 이력에서 다시 볼 수 있나요?
아니요. 웹훅 테스트 결과는 전송 이력에 남지 않습니다. 결과는 웹훅 테스트 창의 응답에서만 확인할 수 있습니다.
Updated 4 days ago