웹훅을 사용하면 Sign.Plus에서 봉투(envelope)의 상태에 대한 실시간 업데이트를 받을 수 있습니다. 이 문서에서는 Sign.Plus 통합을 위해 웹훅을 설정하고 처리하는 과정을 안내합니다.
1단계: 웹훅 만들기
실시간 업데이트를 받으려면 먼저 Sign.Plus에서 웹훅을 만들어야 합니다. 방법은 다음과 같습니다:
- 웹훅 알림을 받을 대상 URL을 결정하세요. 이는 들어오는 POST 요청을 처리할 수 있도록 설정된 서버의 엔드포인트여야 합니다.
- 추적할 이벤트를 선택하세요. Sign.Plus는 다음과 같은 웹훅 이벤트를 제공합니다:
-
envelope_completed- 봉투가 완료되었을 때
-
envelope_expired- 봉투가 만료되었을 때
-
envelope_declined- 봉투가 거부되었을 때
-
envelope_voided- 봉투가 무효화되었을 때
-
- Sign.Plus API를 사용하여 웹훅을 만드세요. 대상 URL과 추적할 이벤트를 지정해야 합니다.
Sign.Plus API를 사용하여 웹훅을 만드는 방법에 대한 자세한 내용은 웹훅 만들기 엔드포인트 문서를 참조하세요.
2단계: 웹훅 알림 처리하기
웹훅을 설정하면 추적된 이벤트가 발생할 때마다 Sign.Plus가 지정한 URL로 POST 요청을 전송합니다. 이러한 알림을 처리할 때 알아야 할 사항은 다음과 같습니다:
-
요청 메서드: 모든 웹훅 알림은 HTTP
POST요청으로 전송됩니다.
-
페이로드 구조: 웹훅 페이로드는 두 가지 주요 섹션을 포함하는 JSON 객체입니다:
-
hook: 웹훅 자체에 대한 메타데이터를 포함합니다.
-
data: 이벤트를 트리거한 봉투에 대한 정보를 포함합니다.
-
-
페이로드 예시: 다음은 다양한 이벤트에 대한 페이로드 예시입니다:
// ENVELOPE_DECLINED
{
"hook": {
"id": "6697ccb204bd194fa74c22b4",
"event": "envelope_declined",
"target": "<https://webhook.site/47acfde3-bd83-4fbc-9ff1-ea0dc030e118>"
},
"data": {
"id": "6697ccb204bd194fa74c22b4",
"uid": "4a6e29bfc5344ca6ad7cc8beda456481",
"envelope_id": "6697e681c5e364c7c23710d4",
"file_name": "test"
}
}
// ENVELOPE_COMPLETED
{
"hook": {
"id": "6697ccb204bd194fa74c22b4",
"event": "envelope_completed",
"target": "<https://webhook.site/47acfde3-bd83-4fbc-9ff1-ea0dc030e118>"
},
"data": {
"id": "6697ccb204bd194fa74c22b4",
"uid": "4a6e29bfc5344ca6ad7cc8beda456481",
"envelope_id": "6697e681c5e364c7c23710d4",
"file_name": "test"
}
}
// ENVELOPE_EXPIRED
{
"hook": {
"id": "6697ccb204bd194fa74c22b4",
"event": "envelope_expired",
"target": "<https://webhook.site/47acfde3-bd83-4fbc-9ff1-ea0dc030e118>"
},
"data": {
"id": "6697ccb204bd194fa74c22b4",
"uid": "4a6e29bfc5344ca6ad7cc8beda456481",
"envelope_id": "6697e681c5e364c7c23710d4",
"file_name": "test"
}
}
// ENVELOPE_VOIDED
{
"hook": {
"id": "6697ccb204bd194fa74c22b4",
"event": "envelope_voided",
"target": "<https://webhook.site/47acfde3-bd83-4fbc-9ff1-ea0dc030e118>"
},
"data": {
"id": "6697ccb204bd194fa74c22b4",
"uid": "4a6e29bfc5344ca6ad7cc8beda456481",
"envelope_id": "6697e681c5e364c7c23710d4",
"file_name": "test"
}
} -
알림 처리: 서버가 웹훅 알림을 수신하면:
- 페이로드를 검증하여 유효한 웹훅 알림인지 확인합니다.
- 페이로드에서 관련 정보를 추출합니다.
- 이벤트 유형에 따라 필요한 작업을 수행합니다(예: 데이터베이스 업데이트, 사용자에게 알림, 다른 프로세스 트리거).
-
웹훅 수신을 확인하기 위해
200 OK응답을 보냅니다.
Sign.Plus 웹훅은 다음 승인된 IP 주소에서만 전송됩니다:
34.65.253.117
34.65.146.131
모범 사례
- 보안: 웹훅 엔드포인트가 안전한지 확인하세요. 웹훅 URL에 대한 인증을 구현하는 것을 고려해 보세요.
- 멱등성: 웹훅 처리기를 멱등적으로 설계하세요. 이는 동일한 웹훅이 여러 번 수신되더라도 동일한 결과를 생성해야 함을 의미합니다.
- 오류 처리: 웹훅 처리 로직에 강력한 오류 처리를 구현하세요.
이 가이드를 따르면 웹훅을 효과적으로 설정하고 처리할 수 있게 되어, 애플리케이션이 Sign.Plus에서 봉투 상태에 대한 실시간 업데이트를 받을 수 있습니다.