Webhook Events

Webhook을 사용하면 문서의 주요 상태 변화를 이벤트로 전달받아 내부 시스템에 반영하거나 후속 작업을 자동화할 수 있습니다.

문서의 서명 / 열람 진행 상태 동기화
문서 상태 변화에 따른 내부 알림이나 후속 작업 실행

받을 이벤트는 웹훅 상세 화면의 구독 이벤트에서 켜고 끌 수 있습니다. 웹훅 추가와 설정 방법은 Webhook 설정을 확인해 주세요.

이벤트별 발생 조건과 예제

새로운 문서로 서명/열람 요청이 시작됨

document_started

{
  "event": {
    "type": "document_started"
  },
  "document": {
    "id": "{DOCUMENT_ID}",
    "requester": {
      "email": "{REQUESTER_EMAIL}"
    }
  }
}

참여자가 문서에 서명을 입력하거나 열람을 완료함

document_signed

{
  "event": {
    "type": "document_signed"
  },
  "document": {
    "id": "{DOCUMENT_ID}",
    "requester": {
      "email": "{REQUESTER_EMAIL}"
    }
  }
}

🚧
주의사항
마지막 참여자의 서명 완료 시에는 발송되지 않습니다.

문서의 모든 참여자가 서명 또는 열람을 완료함

document_all_signed

{
  "event": {
    "type": "document_all_signed"
  },
  "document": {
    "id": "{DOCUMENT_ID}",
    "requester": {
      "email": "{REQUESTER_EMAIL}"
    }
  }
}

참여자가 서명 요청을 거절함

document_rejected

{
  "event": {
    "type": "document_rejected"
  },
  "document": {
    "id": "{DOCUMENT_ID}",
    "requester": {
      "email": "{REQUESTER_EMAIL}"
    }
  }
}

문서의 서명 요청이 취소됨

document_request_canceled

{
  "event": {
    "type": "document_request_canceled"
  },
  "document": {
    "id": "{DOCUMENT_ID}",
    "requester": {
      "email": "{REQUESTER_EMAIL}"
    }
  }
}

참여자가 입력한 서명을 취소함

document_signing_canceled

{
  "event": {
    "type": "document_signing_canceled"
  },
  "document": {
    "id": "{DOCUMENT_ID}",
    "requester": {
      "email": "{REQUESTER_EMAIL}"
    }
  }
}

요청자가 내용 수정을 시작함

document_modification_started

{
  "event": {
    "type": "document_modification_started"
  },
  "document": {
    "id": "{DOCUMENT_ID}",
    "requester": {
      "email": "{REQUESTER_EMAIL}"
    }
  }
}

내용 수정 완료됨

document_modification_completed

{
  "event": {
    "type": "document_modification_completed"
  },
  "document": {
    "id": "{DOCUMENT_ID}",
    "requester": {
      "email": "{REQUESTER_EMAIL}"
    }
  }
}

내부결재로 요청된 문서 수정 완료 후 내부결재 재요청됨

document_modification_approval_requested

{
  "event": {
    "type": "document_modification_approval_requested"
  },
  "document": {
    "id": "{DOCUMENT_ID}",
    "requester": {
      "email": "{REQUESTER_EMAIL}"
    }
  }
}

내용 수정 취소됨

document_modification_canceled

{
  "event": {
    "type": "document_modification_canceled"
  },
  "document": {
    "id": "{DOCUMENT_ID}",
    "requester": {
      "email": "{REQUESTER_EMAIL}"
    }
  }
}

요청 헤더

모두싸인은 모든 Webhook 요청에 아래 헤더를 싣습니다. 같은 이벤트를 다시 보낼 때에도 같은 규칙으로 싣습니다.

헤더	값	설명
`Modusign-Webhook-Id`	Webhook ID	요청을 보낸 Webhook의 ID입니다. Webhook을 삭제하고 같은 주소로 다시 등록하면 새 값이 됩니다.
`Modusign-Delivery-Id`	전송 ID	이벤트 전송 한 건의 ID입니다. 같은 전송을 다시 보낼 때에는 같은 값이 실립니다. 같은 이벤트라도 Webhook이 다르면 값이 다릅니다.
`Modusign-Delivery-Attempt`	시도 번호	같은 전송에서 몇 번째 요청인지 나타냅니다. 첫 요청은 `1`이고, 다시 보낼 때마다 1씩 커집니다.
`Modusign-Timestamp`	요청 시각	요청을 보내기 시작한 시각입니다. Unix epoch 초 단위 정수입니다.
`User-Agent`	`Modusign-Webhook`	Webhook에 `User-Agent` 헤더를 등록했으면 등록한 값이 실립니다.
`Content-Type`	`application/json`	본문 형식입니다.

Webhook에 등록한 사용자 지정 헤더도 함께 실립니다. 단, 위 표의 Modusign-으로 시작하는 헤더 네 개와 이름이 같은 헤더는 등록할 수 없고, 이미 등록되어 있던 헤더는 모두싸인 값으로 바뀌어 실립니다. 자세한 내용은 Webhook 설정을 확인해 주세요.

📘
서명 헤더는 싣지 않습니다
모두싸인 Webhook 요청에는 본문 서명 헤더가 없습니다. 요청을 확인해야 한다면 Webhook에 사용자 지정 헤더(예: 인증 토큰)를 등록해 수신 서버에서 검사해 주세요.

중복 수신 거르기

같은 이벤트가 수신 서버에 두 번 이상 도착할 수 있습니다. 자동 재시도나 웹훅 재전송으로 같은 전송이 다시 오는 경우가 있고, 드물게 같은 시도 번호의 요청이 한 번 더 도착하는 경우도 있습니다.

Modusign-Delivery-Id를 기준으로 이미 처리한 전송인지 확인하면 중복 처리를 막을 수 있습니다.

요청을 받으면 Modusign-Delivery-Id 값을 읽습니다.
이미 처리를 마친 전송 ID이면 2xx로 응답하고 다시 처리하지 않습니다.
처음 받은 전송 ID이면 2xx로 응답한 뒤 처리하고, 처리한 전송 ID를 저장합니다.

Webhook 처리 권장사항

📘
권장 구현 방식

2xx 응답을 먼저 반환한 뒤 내부 작업을 수행합니다.

Modusign-Delivery-Id로 이미 처리한 전송인지 확인해, 같은 이벤트가 여러 번 전달되어도 문제가 없도록 처리합니다.

document.id를 내부 시스템의 문서 식별자와 연결합니다.

필요한 최신 정보는 문서 상세 조회 API로 다시 조회합니다.

실패 및 재시도 정책

Webhook 요청에 대한 응답 상태와 처리 정책은 다음과 같습니다.

조건	실패 처리	재시도
2xx 응답	아니요	아니요
일반적인 2xx 외 응답	예	첫 요청을 포함해 최대 5번 보냅니다(재시도 최대 4번)
401, 404 응답	예	하지 않음
10초 timeout	예	하지 않음

❗️
응답 상태 코드 주의
정상 처리한 이벤트는 반드시 2xx 상태 코드로 응답해야 합니다. 2xx 외 상태 코드로 응답하면 실패로 기록되며, 401 및 404를 제외한 일반적인 실패 응답은 첫 요청을 포함해 최대 5번 보냅니다(재시도 최대 4번).
응답에 10초 이상 소요되면 timeout으로 실패 기록되지만 재시도하지 않습니다.