클라이언트 ID를 가져오고 유효성을 검사한 다음 응답 헤더에 반환하는 샘플 Javascript 코드
마지막 업데이트 날짜
2024년 9월 18일
새로운 기능
시작하기
관리
- Admin Console 개요
- 사용자 관리
- 사용자 추가
- 기능 중심 사용자 생성
- 프로비저닝 오류가 있는 사용자 확인
- 이름/이메일 주소 변경
- 사용자의 그룹 멤버십 편집
- 그룹 인터페이스를 통해 사용자의 그룹 멤버십 편집
- 사용자를 관리자 역할로 승격
- 사용자 ID 유형 및 SSO
- 사용자 ID 전환
- MS Azure로 사용자 인증
- Google Federation으로 사용자 인증
- 제품 프로필
- 로그인 경험
- 계정/그룹 설정
- 설정 개요
- 전역 설정
- 계정 계층 및 ID
- 새로운 수신자 환경
- [자체 서명] 워크플로우
- 대량 전송
- 웹 양식
- 사용자 지정 전송 워크플로우
- Power Automate 워크플로우
- 라이브러리 문서
- 계약서를 사용하여 양식 데이터 수집
- 제한된 문서 표시 여부
- 서명된 계약의 PDF 사본 첨부
- 이메일에 링크 포함
- 이메일에 이미지 포함
- 이메일에 첨부된 파일의 이름 지정
- 문서에 감사 보고서 첨부
- 여러 문서를 하나로 병합
- 개별 문서 다운로드
- 서명된 문서 업로드
- 내 계정의 사용자에 대한 위임
- 외부 수신자의 위임 허용
- 서명 권한
- 전송 권한
- 전자 봉인 추가 권한
- 기본 시간대 설정
- 기본 날짜 형식 설정
- 다중 그룹의 사용자(UMG)
- 그룹 관리자 권한
- 수신자 바꾸기
- 감사 보고서
- 트랜잭션 꼬리말
- 제품 내 메시지 및 지침
- 액세스할 수 있는 PDF
- 새로운 작성 환경
- 의료 고객
- 계정 설정
- 로고 추가
- 회사 호스트 이름/URL 사용자 지정
- 회사 이름 추가
- 계약 후 URL 리디렉션
- 서명 기본 설정
- 서식이 올바르게 지정된 서명
- 수신자의 서명 허용
- 서명자 이름 변경 가능
- 수신자가 자신이 저장한 서명을 사용하도록 허용
- 사용자 지정 사용 약관 및 소비자 공개
- 폼 필드를 통해 수신자 탐색
- 계약 워크플로우 다시 시작
- 서명 거부
- 스탬프 워크플로우 허용
- 서명자에게 직책 또는 회사 제공 요청
- 서명자의 자필 서명 인쇄 및 배치 허용
- 전자 서명 시 메시지 표시
- 서명자가 모바일 장치를 사용하여 서명을 작성하도록 요청
- 서명자의 IP 주소 요청
- 참여 스탬프에서 회사 이름 및 직책 제외
- 디지털 서명
- 전자 봉인
- 디지털 신원
- 보고서 설정
- 새로운 보고서 환경
- 기존 보고서 설정
- 보안 설정
- 전송 설정
- 로그인 후 전송 페이지 표시
- 전송 시 수신자 이름 필요
- 알려진 사용자에 대한 이름 값 잠금
- 허용된 수신자 역할
- 전자 증명자 허용
- 수신자 그룹
- CC
- 수신자 계약 액세스
- 필수 필드
- 문서 첨부
- 필드 결합
- 계약 수정
- 계약 이름
- 언어
- 개인 메시지
- 허용되는 서명 유형
- 알림 메시지
- 서명된 문서 암호 보호
- 다음을 통해 계약 알림 전송
- 서명자 식별 옵션
- 콘텐츠 보호
- Notarize 트랜잭션 활성화
- 문서 만료
- 서명 미리 보기, 배치 및 필드 추가
- 서명 순서
- Liquid Mode
- 사용자 지정 워크플로우 제어
- 전자 서명 페이지 업로드 옵션
- 서명 후 확인 URL 리디렉션
- 메시지 템플릿
- Bio-Pharma 설정
- 워크플로우 통합
- 공증 설정
- 결제 통합
- 서명자 메시징
- SAML 설정
- SAML 구성
- Microsoft Active Directory Federation 서비스 설치
- Okta 설치
- OneLogin 설치
- Oracle Identity Federation 설치
- SAML 구성
- 데이터 거버넌스
- 타임 스탬프 설정
- 외부 보관
- 계정 언어
- 이메일 설정
- echosign.com에서 adobesign.com으로 마이그레이션합니다.
- 수신자 옵션 구성
- 규정 요구 사항 지침
- 계약서 일괄 다운로드
- 도메인 요청
- 오용 신고 링크
계약 전송, 서명 및 관리
- 수신자 옵션
- 계약 보내기
- 문서에 필드 작성
- 인앱 작성 환경
- 텍스트 태그로 폼 만들기
- Acrobat으로 폼 만들기(AcroForm)
- 필드
- 작성 FAQ
- 계약 서명
- 계약 관리
- 감사 보고서
- 보고 및 데이터 내보내기
고급 계약 기능 및 워크플로우
- 웹 양식
- 재사용 가능 템플릿(라이브러리 템플릿)
- 웹 양식 및 라이브러리 템플릿의 소유권 이전
- Power Automate 워크플로우
- Power Automate 통합 및 포함된 권한 개요
- Power Automate 통합 활성화
- 관리 페이지의 컨텍스트별 작업
- Power Automate 사용 추적
- 새 플로우 만들기(예시)
- 플로우에 사용되는 트리거
- Acrobat Sign 외부에서 플로우 가져오기
- 플로우 관리
- 플로우 편집
- 플로우 공유
- 플로우 비활성화 또는 활성화
- 플로우 삭제
- 템플릿 사용
- 관리자만
- 계약 보관
- 웹 양식 계약 보관
- 작성한 웹 양식 문서를 SharePoint 라이브러리에 저장
- 작성한 웹 양식 문서를 OneDrive for Business에 저장
- 작성한 문서를 Google Drive에 저장
- 작성한 웹 양식 문서를 Box에 저장
- 계약 데이터 추출
- 계약 알림
- 계약 콘텐츠 및 서명된 계약서와 함께 사용자 지정 이메일 알림 전송
- Teams 채널에서 Adobe Acrobat Sign 알림 받기
- Slack에서 Adobe Acrobat Sign 알림 받기
- Webex에서 Adobe Acrobat Sign 알림 받기
- 계약 생성
- Power App 양식 및 Word 템플릿에서 문서를 생성하고 서명을 위해 전송
- OneDrive의 Word 템플릿에서 계약 생성 및 서명 받기
- 선택한 Excel 행에 대한 계약 생성, 검토를 위해 보내기 및 서명
- 사용자 지정 전송 워크플로우
- 사용자 및 계약 공유
다른 제품과 통합
- Acrobat Sign 통합 개요
- Salesforce용 Acrobat Sign
- Microsoft용 Acrobat Sign
- 기타 통합
- 파트너 관리 통합
- 통합 키 획득 방법
Acrobat Sign 개발자
- REST API
- Webhook
지원 및 문제 해결
개요
Webhook은 소스 사이트(이 경우 Adobe Acrobat Sign)에서 구독 이벤트가 발생할 때 트리거되는 사용자 지정된 HTTPS 요청입니다.
사실상 Webhook은 데이터 또는 데이터 스트림을 수락하는 REST 서비스에 불과합니다.
Webhook은 푸시 모델에서 서비스 간 통신을 위한 것입니다.
구독 이벤트가 트리거되면 Acrobat Sign은 JSON 본문을 사용하여 HTTPS POST를 구성하고 지정된 URL로 전달합니다.
Webhook을 구성하기 전에 네트워크가 기능에 필요한 IP 범위를 허용하는지 확인하세요.
Webhook은 이전 콜백 방법에 비해 여러 가지 이점을 제공하며, 그중 일부는 다음과 같습니다.
- 관리자는 콜백 URL을 나열하기 위해 Acrobat Sign 지원을 사용할 필요 없이 Webhook을 활성화할 수 있습니다.
- Webhook은 데이터 “참신성”, 통신의 효율성, 보안 측면에서 더 유용합니다. 폴링은 필요하지 않습니다.
- Webhook을 사용하면 다양한 수준의 범위(계정/그룹/사용자/리소스)를 쉽게 지원할 수 있습니다.
- Webhook은 최신 API 솔루션으로, 최신 애플리케이션을 더 간단하게 구성할 수 있습니다.
- 각 범위(계정/그룹/사용자/리소스)에 대해 여러 Webhook을 구성할 수 있습니다. 여기서 콜백은 고유해야 합니다.
- Webhook을 사용하면 반환할 데이터를 선택할 수 있습니다. 여기서 콜백은 "전부 아니면 전무" 솔루션입니다.
- Webhook과 함께 제공되는 메타데이터를 구성할 수 있습니다(기본 또는 상세).
- UI가 전적으로 관리자의 제어 범위 내에 있으므로 Webhook을 필요에 따라 훨씬 쉽게 생성, 편집 또는 비활성화할 수 있습니다.
참고:
이 문서에서는 주로 Acrobat Sign 웹 애플리케이션(이전 Adobe Sign)의 Webhook UI를 중점적으로 다룹니다.
API 세부 정보를 찾는 개발자는 여기에서 추가 정보를 찾을 수 있습니다.
사전 요구 사항
서비스가 작동하려면 네트워크 보안을 통해 Webhook의 IP 범위를 허용해야 합니다.
REST v5의 레거시 콜백 URL 서비스는 Webhook 서비스와 동일한 IP 범위를 사용합니다.
관리자는 Adobe Admin Console에 로그인하여 사용자를 추가할 수 있습니다. 로그인한 후 관리자 메뉴로 이동하여 Webhook으로 스크롤합니다.
사용되는 방식
관리자는 먼저 Acrobat Sign의 인바운드 푸시를 수락할 준비가 된 Webhook 서비스를 보유해야 합니다. 관련된 많은 옵션이 있으며, 서비스가 POST 및 GET 요청을 수락할 수 있는 한 Webhook은 성공적으로 실행됩니다.
서비스가 준비되면 Acrobat Sign 관리자는 Acrobat Sign 사이트의 계정 메뉴에 있는 Webhook 인터페이스에서 새 Webhook을 생성할 수 있습니다.
관리자는 계약, 웹 양식(위젯) 또는 대량 전송(MegaSign) 이벤트를 트리거하도록 Webhook을 구성할 수 있습니다. 라이브러리 템플릿(라이브러리 문서) 리소스는 API를 통해 구성할 수도 있습니다.
Webhook의 범위는 관리자 인터페이스를 통해 전체 계정 또는 개별 그룹을 포함할 수 있습니다. API를 사용하면 사용자 또는 리소스 범위를 선택하여 더 세분화할 수 있습니다.
URL로 푸시되는 데이터 유형은 구성 가능하며 계약 정보, 참가자 정보, 문서 정보 등과 같은 항목을 포함할 수 있습니다.
Webhook이 구성되고 저장되면 Acrobat Sign은 구독 이벤트가 트리거될 때마다 새로운 JSON 개체를 정의된 URL로 푸시합니다. 이벤트 트리거 조건이나 JSON 페이로드를 변경하려는 경우가 아니라면 Webhook을 계속 조작할 필요가 없습니다.
Webhook URL의 의도 확인
Webhook을 성공적으로 등록하기 전에 Acrobat Sign은 등록 요청에서 제공된 Webhook URL이 알림을 수신할 것인지 여부를 확인합니다. 이를 위해 Acrobat Sign은 새 Webhook 등록 요청을 받으면 먼저 Webhook URL에 대한 확인 요청을 합니다. 이 확인 요청은 Webhook URL로 전송된 HTTPS GET 요청입니다. 이 요청에는 사용자 지정 HTTP 헤더 X-AdobeSign-ClientId가 있습니다. 이 헤더의 값은 Webhook 생성/등록을 요청하는 API 애플리케이션의 클라이언트 ID(애플리케이션 ID)로 설정됩니다. Webhook을 성공적으로 등록하려면 Webhook URL은 이 확인 요청에 2XX 응답 코드로 응답해야 하며 다음 두 가지 방법 중 하나로 동일한 클라이언트 ID 값을 다시 전송해야 합니다.
- 응답 헤더 X-AdobeSign-ClientId에서 이는 요청에서 전달되는 동일한 헤더로 응답에서 다시 반복됩니다.
- 또는 xAdobeSignClientId 키가 포함된 JSON 응답 본문에서 해당 값은 요청에서 전송된 것과 동일한 클라이언트 ID입니다.
Webhook은 성공 응답(2XX 응답 코드) 및 헤더 또는 응답 본문의 클라이언트 ID 유효성 검사에만 성공적으로 등록됩니다. 이 확인 요청의 목적은 Webhook URL이 해당 URL에서 알림을 수신하기를 원한다는 것을 보여주기 위한 것입니다. 실수로 잘못된 URL을 입력한 경우 URL이 의도 요청 확인에 올바르게 응답하지 않으며 Acrobat Sign이 해당 URL에 알림을 전송하지 않습니다. 또한 Webhook URL은 특정 애플리케이션에서 등록한 Webhook을 통해서만 알림을 수신하는지 확인할 수도 있습니다. 이 작업은 X-AdobeSign-ClientId 헤더에 전달된 애플리케이션의 클라이언트 ID를 유효성 검사하여 수행할 수 있습니다. Webhook URL이 해당 클라이언트 ID를 인식하지 못하면 성공 응답 코드로 응답하지 않아야 하며, Acrobat Sign은 URL이 Webhook으로 등록되지 않도록 처리합니다.
Webhook URL 호출의 확인은 다음 시나리오에서 수행됩니다.
- Webhook 등록: 이 Webhook URL 호출 확인에 실패하면 Webhook이 생성되지 않습니다.
- Webhook 업데이트: INACTIVE - ACTIVE: 이 Webhook URL 호출 확인에 실패하면 Webhook 상태가 ACTIVE로 변경되지 않습니다.
Webhook 알림에 응답하는 방법
Acrobat Sign은 Webhook URL로 전송되는 각 Webhook 알림 요청에서 의도를 암시적으로 확인합니다. 따라서 모든 Webhook 알림 HTTPS 요청에는 X-AdobeSign-ClientId라는 사용자 지정 HTTP 헤더도 포함됩니다. 이 헤더의 값은 Webhook을 생성한 애플리케이션의 클라이언트 ID(애플리케이션 ID)입니다. 성공 응답(2XX 응답 코드)이 반환되고 클라이언트 ID가 HTTP 헤더(X-AdobeSign-ClientId)로 전송되거나 키가 xAdobeSignClientId이고 값이 동일한 클라이언트 ID인 JSON 응답 본문을 통해 전송되는 경우에만 Webhook 알림이 성공적으로 전달된 것으로 간주합니다. 그렇지 않으면 재시도 횟수가 모두 소진될 때까지 Webhook URL로 알림 전달을 다시 시도합니다.
위에 언급한 것처럼 Sign의 모든 알림 요청에 포함된 헤더 'X-AdobeSign-ClientId'와 이 헤더의 값(클라이언트 ID)을 다음 두 가지 방법 중 하나로 응답에서 다시 반복해야 합니다.
1. HTTP 헤더 X-AdobeSign-ClientId 및 이 클라이언트 ID인 값
|
|
|---|
|
//클라이언트 ID를 가져옵니다. var clientid = request.headers['X-ADOBESIGN-CLIENTID'];
//유효성을 검사합니다. if (clientid ==="BGBQIIE7H253K6") //'BGBQIIE7H253K6'을 Webhook을 생성하는 데 사용하는 애플리케이션의 클라이언트 ID로 교체합니다. { //응답 헤더에 반환합니다. response.headers['X-AdobeSign-ClientId'] = clientid; response.status = 200; //기본값 } |
|
클라이언트 ID를 가져오고 유효성을 검사한 다음 응답 헤더에 반환하는 샘플 PHP 코드 |
|---|
|
<?php //클라이언트 ID를 가져옵니다. $clientid = $_SERVER['HTTP_X_ADOBESIGN_CLIENTID']; //유효성을 검사합니다. if($clientid == "BGBQIIE7H253K6") //'BGBQIIE7H253K6'을 Webhook을 생성하는 데 사용하는 애플리케이션의 클라이언트 ID로 교체합니다. { //응답 헤더에 반환합니다. header("X-AdobeSign-ClientId:$clientid"); header("HTTP/1.1 200 OK"); // default value } ?> |
2. 키가 xAdobeSignClientId이고 값이 동일한 클라이언트 ID인 JSON 응답 본문
|
클라이언트 ID를 가져오고 유효성을 검사한 다음 응답 본문에 반환하는 샘플 Javascript 코드 |
|---|
|
//클라이언트 ID를 가져옵니다. var clientid = request.headers['X-ADOBESIGN-CLIENTID'];
//유효성을 검사합니다. if (clientid ==="BGBQIIE7H253K6") //'BGBQIIE7H253K6'을 Webhook을 생성하는 데 사용하는 애플리케이션의 클라이언트 ID로 교체합니다. { var responseBody = { "xAdobeSignClientId" : clientid // Return Client Id in the body }; response.headers['Content-Type'] = 'application/json'; response.body = responseBody; response.status = 200; } |
|
클라이언트 ID를 가져오고 유효성을 검사한 다음 응답 본문에 반환하는 샘플 PHP 코드 |
|---|
|
<?php //클라이언트 ID를 가져옵니다. $clientid = $_SERVER['HTTP_X_ADOBESIGN_CLIENTID']; //유효성을 검사합니다. if($clientid == "BGBQIIE7H253K6") //'BGBQIIE7H253K6'을 Webhook을 생성하는 데 사용하는 애플리케이션의 클라이언트 ID로 교체합니다. { //Return it in response body header("Content-Type: application/json"); $body = array('xAdobeSignClientId' => $clientid); echo json_encode($body); header("HTTP/1.1 200 OK"); // default value } ?> |
|
응답의 샘플 JSON 본문 |
|---|
|
{ "xAdobeSignClientId": "BGBQIIE7H253K6" } |
사전 요구 사항
필수 항목:
- Azure 함수 애플리케이션을 만들기 위한 라이선스가 있는 Microsoft 계정
- 기존 Azure 함수 애플리케이션은 https://docs.microsoft.com/ko-kr/azure/azure-functions/functions-create-first-azure-function을 사용하여 만들 수 있습니다.
- 원하는 언어로 코드를 이해하고 작성할 수 있도록 하기 위한 자바스크립트에 대한 기본 지식
Acrobat Sign Webhook 역할을 하는 Azure 함수 트리거를 만드는 단계
Javascript HTTP Trigger 함수를 생성하는 방법은 다음과 같습니다.
1. Microsoft 계정을 통해 로그인합니다(https://portal.azure.com/).
2. 함수 앱 탭에 표시된 Azure 함수 애플리케이션을 엽니다.
Azure 함수 애플리케이션 목록이 열립니다.
3. 이 새 함수를 만들 애플리케이션을 선택합니다.
4. 만들기(+) 버튼을 클릭하여 새 Azure 함수를 만듭니다.
5. Webhook + API를 시나리오로 선택하고 Javascript를 언어로 선택합니다.
6. 이 함수 만들기를 클릭합니다.
수신 API 요청을 처리할 수 있는 새 함수가 만들어집니다.
Acrobat Sign Webhook을 등록하는 논리 추가
Webhook을 성공적으로 등록하기 전에 Acrobat Sign은 등록 요청에서 제공된 Webhook URL이 실제로 알림을 수신할 의도가 있는지 여부를 확인합니다. 이를 위해 Acrobat Sign에서 새로운 Webhook 등록 요청을 받으면 우선 Webhook URL에 확인 요청을 합니다. 이 확인 요청은 사용자 지정 HTTP 헤더 X-AdobeSign-ClientId가 있는 Webhook URL로 전송되는 HTTPS GET 요청입니다. 이 헤더의 값은 Webhook 생성/등록을 요청하는 애플리케이션의 클라이언트 ID로 설정됩니다. Webhook을 성공적으로 등록하기 위하여 Webhook URL은 2XX 응답 코드로 해당 확인 요청에 응답해야 하며 다음 두 가지 방법 중 하나로 동일한 클라이언트 ID 값을 다시 전송해야 합니다.
다음과 같은 두 가지 옵션을 사용할 수 있습니다.
옵션 1. X-AdobeSign-ClientId의 클라이언트 ID를 응답 헤더로 전달
X-AdobeSign-ClientId를 응답 헤더로 전달합니다. 이는 요청에서 전달되는 동일한 헤더로 응답에서 다시 반복해야 합니다.
Index.js 파일을 다음으로 바꿉니다.
module.exports = function (context, req) {
var clientId = req.headers['x-adobesign-clientid'];
//수신 ClientID가 정품인지 확인합니다.
if (clientId === '123XXX456') {
context.res = {
// status: 200, /* Defaults to 200 */ // 모든 2XX 응답이 허용됩니다.
body: "Notification Accepted",
headers : {
'x-adobesign-clientid' : req.headers['x-adobesign-clientid']
}
};
}
else {
context.res = {
status: 400,
body: "Opps!! Illegitimate Call identified"
};
}
context.done();
};
요청 시안을 만들어 동작을 테스트합니다.
1. 맨 오른쪽 모서리에 있는 테스트 버튼을 클릭합니다.
2. 더미 요청 시안을 만듭니다.
응답 헤더는 위에 표시되지 않지만, postman/DHC 또는 기타 다른 서비스로 시안을 만들어 관찰할 수 있습니다.
옵션 2. xAdobeSignClientId 키를 사용하여 응답 본문에 클라이언트 ID 전달
xAdobeSignClientId 키가 포함된 JSON 응답 본문에서 해당 값은 요청에서 전송된 것과 동일한 클라이언트 ID입니다.
Index.js 파일을 다음으로 바꿉니다.
module.exports = function (context, req) {
var clientId = req.headers['x-adobesign-clientid'];
//수신 ClientID가 정품인지 확인합니다.
if (clientId === '123XXX456') {
context.res = {
// status: 200, /* Defaults to 200 */ // 모든 2XX 응답이 허용됩니다.
body: {
'xAdobeSignClientId' : clientId
},
headers : {
'Content-Type' : 'application/json'
}
};
}
else {
context.res = {
status: 400,
body: "Opps!! Illegitimate Call identified"
};
}
context.done();
};
요청 시안을 만들어 동작을 테스트합니다.
1. 맨 오른쪽 모서리에 있는 테스트 버튼을 클릭합니다.
2. 더미 요청 시안을 만듭니다.
또한 Webhook URL이 POST 알림을 받을 때 clientID에 대해서도 동일한 동작이 예상됩니다.
사용 준비됨
동작을 확인하면 Acrobat Sign 표준에 따라 Webhook URL이 작동합니다. 요구 사항에 따라 사용자 지정 논리를 추가로 업데이트할 수 있습니다.
함수 URL 가져오기
- 함수 URL 가져오기를 클릭합니다.
URL을 복사하여 Acrobat Sign에서 Webhook을 만드는 데 사용합니다.
AWS Lambda 함수 만들기
AWS Lambda 함수를 만들려면 AWS Management Console에 로그인하여 서비스 목록에서 AWS Lambda 서비스를 선택합니다.
- "처음부터 작성"을 사용하여 Lambda 함수 만들기 옵션을 클릭합니다.
- 함수 구성 페이지에서 기능 이름 "lambdaWebhooks"를 입력하고 Node.js 4.3을 런타임으로 선택합니다.
- 역할의 경우 기존 역할을 선택하거나 템플릿에서 새 역할을 만듭니다.
- 템플릿에서 새 역할 만들기를 선택한 경우 역할 이름(예: role-lambda)을 입력하고 정책 템플릿 목록에서 단순 마이크로서비스 권한을 선택합니다.
- 함수 생성 버튼을 클릭합니다.
- 새 AWS Lambda 함수 페이지에서 "코드 인라인 편집"을 "코드 입력 유형"으로 선택하고 index.handler를 핸들러로 유지합니다.
- Acrobat Sign Webhook을 등록하는 논리 추가
Webhook을 성공적으로 등록하기 전에 Acrobat Sign은 등록 요청에서 제공된 Webhook URL이 실제로 알림을 수신할 의도가 있는지 여부를 확인합니다. 이를 위해 Acrobat Sign에서 새로운 Webhook 등록 요청을 받으면 우선 Webhook URL에 확인 요청을 합니다. 이 확인 요청은 사용자 지정 HTTP 헤더 X-AdobeSign-ClientId가 있는 Webhook URL로 전송되는 HTTPS GET 요청입니다. 이 헤더의 값은 Webhook 생성/등록을 요청하는 애플리케이션의 클라이언트 ID로 설정됩니다. Webhook을 성공적으로 등록하기 위하여 Webhook URL은 2XX 응답 코드로 해당 확인 요청에 응답해야 하며 다음 두 가지 방법 중 하나로 동일한 클라이언트 ID 값을 다시 전송해야 합니다. 또한 Webhook URL이 POST 알림을 받을 때 clientID에 대해서도 동일한 동작이 예상됩니다.
다음 두 가지 경우 중 하나를 수행합니다.
사례 1: X-AdobeSign-ClientId의 클라이언트 ID를 응답 헤더로 전달
- X-AdobeSign-ClientId를 응답 헤더로 전달합니다. 이는 요청에서 전달되는 동일한 헤더로 응답에서 다시 반복해야 합니다.
코드 조각
index.js 파일에서 자동으로 생성된 코드 조각을 다음 코드로 바꿉니다.
- X-AdobeSign-ClientId를 응답 헤더로 전달합니다. 이는 요청에서 전달되는 동일한 헤더로 응답에서 다시 반복해야 합니다.
|
클라이언트 ID를 가져오고 유효성을 검사한 다음 응답 헤더에 반환하는 샘플 노드 JS 코드 |
|---|
|
exports.handler = function index(event, context, callback) { //클라이언트 ID를 가져옵니다. var clientid = event.headers['X-AdobeSign-ClientId'];
//유효성을 검사합니다. if (clientid =="BGBQIIE7H253K6") //'BGBQIIE7H253K6'을 Webhook을 생성하는 데 사용하는 애플리케이션의 클라이언트 ID로 교체합니다. { var response = { statusCode: 200, headers: { "X-AdobeSign-ClientId": clientid } }; callback(null,response); } else { callback("Oops!! illegitimate call"); } } |
사례 2: xAdobeSignClientId 키를 사용하여 응답 본문에 클라이언트 ID 전달
xAdobeSignClientId 키가 포함된 JSON 응답 본문에서 해당 값은 요청에서 전송된 것과 동일한 클라이언트 ID입니다.
코드 조각
Index.js 파일을 다음으로 바꿉니다.
|
클라이언트 ID를 가져오고 유효성을 검사한 다음 응답 헤더에 반환하는 샘플 노드 JS 코드 |
|---|
|
exports.handler = function index(event, context, callback) { //클라이언트 ID를 가져옵니다. var clientid = event.headers['X-AdobeSign-ClientId'];
//유효성을 검사합니다. if (clientid =="BGBQIIE7H253K6") //'BGBQIIE7H253K6'을 Webhook을 생성하는 데 사용하는 애플리케이션의 클라이언트 ID로 교체합니다. { var responseBody = { xAdobeSignClientId : clientid };
var response = { statusCode: 200, body: JSON.stringify(responseBody) };
callback(null,response); } else { callback("Opps!! illegitimate call"); } } |
- 함수를 저장합니다. Lambda 함수가 생성되며 실시간 Webhook에서 사용할 준비가 거의 다 되었습니다.
AWS API Gateway 구성
HTTP 메서드를 통해 이 Lambda에 공개적으로 액세스할 수 있도록 하려면 위에서 만든 함수를 API의 백엔드로 사용하여 AWS API Gateway를 구성해야 합니다.
AWS Management Console의 AWS 서비스에서 API Gateway를 선택하고 API 만들기 버튼을 클릭합니다.
- 새 API 만들기 페이지에서 새 API를 선택하고 webhooks를 API 이름으로 입력합니다.
- API 만들기 버튼을 클릭합니다.
- 작업 드롭다운 목록을 선택하고 리소스 만들기 옵션을 선택합니다.
- 프록시 리소스로 구성 옵션을 확인하고 validate를 리소스 이름으로, {proxy+}를 리소스 경로로 입력합니다.
- API Gateway CORS 활성화 옵션을 선택 취소된 상태로 유지하고 리소스 만들기 버튼을 클릭합니다.
- Lambda 함수 프록시를 통합 유형으로 선택된 상태로 유지하고 Lambda 리전 드롭다운 목록에서 Lambda 함수를 만든 리전을 선택합니다(API Gateway를 생성하는 리전과 동일한 리전일 수 있음).
- validate를 Lambda 함수로 입력하고 저장 버튼을 클릭합니다.
- Lambda 함수에 권한 추가 팝업 창에서 확인을 선택합니다.
위의 모든 단계가 성공적으로 실행되면 다음과 같은 항목이 표시됩니다.
API 배포
다음 단계는 이 API를 배포하여 사용할 준비를 하는 것입니다.
- 작업 드롭다운에서 API 배포를 선택합니다.
- 배포 단계에서 [새 단계]를 선택하고 단계 이름에 prod(또는 이 단계를 식별할 수 있는 모든 것)를 입력합니다.
- 배포 버튼을 클릭합니다.
이제 API를 사용할 준비가 되었으며 아래와 같이 파란색 상자에서 호출 URL을 찾을 수 있습니다.
이 URL은 실시간 Webhook URL로 입력해야 하므로 기록해 두세요.
사용 준비됨
완료되었습니다. POST /webhooks API 요청에서 webhook url로 추가된 "/{nodeJSfunctionName}"과 함께 위 URL을 사용하세요. 동작을 확인하면
Acrobat Sign 표준에 따라 Webhook URL이 작동합니다. 요구 사항에 따라 사용자 지정 논리를 추가로 업데이트/추가할 수 있습니다.
활성화하거나 비활성화하는 방법
Webhooks 기능에 대한 액세스는 엔터프라이즈 계층 계정에서 기본적으로 활성화되어 있습니다.
그룹 수준 관리자는 해당 그룹 내에서만 작동하는 Webhook을 만들거나 제어할 수 있습니다.
Webhooks 페이지에 대한 액세스는 관리 메뉴의 왼쪽 레일에서 찾을 수 있습니다.
동시성 기반 빈도 제한
Webhook(및 콜백) 생성 및 알림 이벤트는 Acrobat Sign 시스템에서 고객에게 능동적으로 전달되는 동시 알림 수에서 제한됩니다. 이 제한은 계정에 적용되며, 계정의 모든 그룹을 포함합니다.
이러한 속도 제한 유형은 불량하게 설계된 계정 한 개가 서버 리소스의 불균형한 양을 소비하지 못하도록 함으로써 해당 서버 환경의 다른 모든 고객에게 부정적인 영향을 줍니다.
계정당 동시 이벤트 수는 제대로 동작하는 Webhook이 있는 계정이 가장 짧은 시간 내에 알림을 받도록 계산되었으며 너무 많은 요청으로 인해 알림이 지연되는 경우는 거의 나타나지 않습니다. 현재 임계값은 다음과 같습니다.
|
작업 |
최대 |
설명 |
|
Webhook 만들기 |
10 |
계정당 최대 10개의 동시 Webhook 생성 요청이 허용됩니다. |
|
Webhook/콜백 알림 |
30 |
계정당 최대 30개의 동시 Webhook 및 콜백 알림이 허용됩니다. |
우수 사례
- 필요한 특정 이벤트를 구독하여 서버에 대한 HTTPS 요청 수 제한 - Webhook을 구체화할수록 살펴볼 볼륨은 줄어듭니다.
- 중복 방지 - 동일한 Webhook URL을 공유하는 여러 앱이 있고 동일한 사용자가 각 앱에 매핑된 경우 동일한 이벤트가 여러 번 Webhook로 전송됩니다(앱당 한 번). 경우에 따라 Webhook에서 중복 이벤트를 받을 수 있습니다. Webhook 애플리케이션은 이를 허용해야 하며 이벤트 ID에 의해 중복 제거되어야 합니다.
- 항상 신속하게 Webhook에 응답 - 앱이 Webhook 요청에 응답할 수 있는 시간은 단 5초입니다. 확인 요청의 경우, 앱에서 응답하기 위해 실제 작업을 수행할 필요가 없으므로 거의 문제가 되지 않습니다. 그러나 알림 요청의 경우, 일반적으로 앱에서 요청에 응답하는 데 시간이 걸리는 작업을 수행합니다. 5초 이내에 응답할 수 있도록 별도의 스레드에서 작업하거나 대기열을 비동기적으로 사용하는 것이 좋습니다.
- 동시성 관리 - 사용자가 여러 사항을 연속적으로 빠르게 변경하면 앱에서 거의 동시에 동일한 사용자에 대한 여러 알림을 수신할 가능성이 높습니다. 동시성을 관리하는 방법에 대해 주의하지 않으면 앱에서 동일한 사용자에 대한 동일한 변경 내용을 두 번 이상 처리할 수 있습니다. Acrobat Sign Webhook을 활용하려면 정보 사용에 대한 명확한 이해가 필요합니다. 다음과 같이 질문하세요.
- 페이로드에서 어떤 데이터를 반환하시겠습니까?
- 누가 이 정보에 액세스하게 되나요?
- 어떤 결정 또는 보고가 생성되나요?
- 서명된 문서 수신을 위한 권장 사항 - 문서 관리 시스템에서 Acrobat Sign의 서명된 PDF를 수신하는 방법을 결정할 때 고려할 몇 가지 요소가 있습니다.
Webhook을 만드는 동안 서명된 계약 문서 옵션을 선택하는 것이 완벽하게 허용되지만, 트리거 이벤트(예: 계약 상태 완료)가 수신되면 Acrobat Sign API를 사용하여 문서를 검색하는 것을 고려할 수 있습니다.
주의 사항...
JSON 크기 제한
JSON 페이로드 크기는 10MB로 제한됩니다.
이벤트에서 더 큰 페이로드를 생성하는 경우 Webhook이 트리거되지만 요청에 조건부 매개변수 속성이 있는 경우 이를 제거하여 페이로드의 크기를 줄입니다.
이런 일이 발생하면 응답에 "ConditionalParametersTrimmed"가 반환되어, 클라이언트에게 conditionalParameters 정보가 제거되었음을 알립니다.
“conditionalParametersTrimmed”는 트리밍된 키에 대한 정보가 포함된 배열 개체입니다.
잘라내기는 다음 순서로 수행됩니다.
- includeSignedDocuments
- includeParticipantsInfo
- includeDocumentsInfo
- includeDetailedInfo
서명된 문서가 먼저 잘린 다음 참가자 정보, 문서 정보, 마지막으로 세부 정보가 잘립니다.
예를 들어 서명된 문서(base 64 인코딩)가 포함되어 있는 계약 완료 이벤트에서 또는 여러 양식 필드가 있는 계약에 대해 이러한 문제가 발생할 수 있습니다.
Acrobat Sign Webhook는 계약 발신자와 계약이 전송된 그룹 내에 구성된 모든 Webhook에 알림을 보냅니다. 계정 범위 Webhook는 모든 이벤트를 받습니다.
발신자: 사용자 A | 서명자: 사용자 B | 피공유자: 사용자 C
사용자 A와 사용자 B가 다른 계정에 있습니다.
사용자 A와 사용자 C가 다른 계정에 있습니다.
사용 사례 |
알림? |
코멘트/메모 |
사용자 A의 계정에 계정 수준 Webhook(사용자 A 또는 계정 관리자가 생성)가 있습니다. |
예 |
계정 수준 Webhook는 해당 계정에서 트리거된 모든 이벤트에 대한 알림을 받습니다. |
사용자 A의 계정에 그룹 수준 Webhook(사용자 A 또는 계정/그룹 관리자가 생성)가 있습니다. 가정: 사용자 A와 그룹 관리자가 동일한 그룹에 있습니다. |
예 |
그룹 수준 Webhook는 해당 그룹에서 트리거된 모든 이벤트에 대한 알림을 받습니다. |
사용자 A에게 사용자 수준 Webhook가 있습니다. |
예 |
전송자로서 사용자 A의 사용자 수준 Webhook가 트리거됩니다. |
사용자 A에게 (위의 전송된 계약에 대한) 리소스 수준 Webhook가 있습니다. |
예 |
|
사용자 B의 계정에 계정 수준 Webhook(사용자 B 또는 계정 관리자가 생성)가 있습니다. |
아니요 |
사용자 B의 계정 수준 Webhook는 서명자 Webhook로 간주됩니다. |
사용자 B의 계정에 그룹 수준 Webhook(사용자 B 또는 계정/그룹 관리자가 생성)가 있습니다. 가정: 사용자 B와 그룹 관리자가 동일한 그룹에 있습니다. |
아니요 |
사용자 B의 그룹 수준 Webhook는 서명자 Webhook로 간주됩니다. |
사용자 B에게 사용자 수준 Webhook가 있습니다. |
아니요 |
사용자 B의 사용자 수준 Webhook는 서명자 Webhook로 간주됩니다. |
사용자 C의 계정에 계정 수준 Webhook(사용자 C 또는 계정 관리자가 생성)가 있습니다. |
아니요 |
사용자 C의 계정 수준 Webhook는 비 작성자 Webhook로 간주됩니다. |
사용자 C의 계정에 그룹 수준 Webhook(사용자 C 또는 계정/그룹 관리자가 생성)가 있습니다. 가정: 사용자 C와 그룹 관리자가 동일한 그룹에 있습니다. |
아니요 |
사용자 C의 그룹 수준 Webhook는 비 작성자 Webhook로 간주됩니다. |
사용자 C에게 사용자 수준 Webhook가 있습니다. |
아니요 |
사용자 C의 사용자 수준 Webhook는 비 작성자 Webhook로 간주됩니다. |
발신자: 사용자 A | 서명자: 사용자 B | 피공유자: 사용자 C
사용자 A, 사용자 B, 사용자 C가 동일한 계정에 있습니다.
사용 사례 |
알림? |
노트 추가 |
사용자 A의 계정에 계정 수준 Webhook(사용자 A 또는 계정 관리자가 생성)가 있습니다. |
예 |
계정 수준 Webhook는 계정에서 트리거된 이벤트를 알립니다. |
사용자 A의 계정에 그룹 수준 Webhook(사용자 A 또는 계정/그룹 관리자가 생성)가 있습니다. 가정: 사용자 A와 그룹 관리자가 동일한 그룹에 있습니다. |
예 |
그룹 수준 Webhook는 그룹의 사용자가 트리거한 이벤트를 알립니다. |
사용자 A에게 사용자 수준 Webhook가 있습니다. |
예 |
전송자로서 사용자 A의 사용자 수준 Webhook가 트리거됩니다. |
사용자 A에게 (위의 전송된 계약에 대한) 리소스 수준 Webhook가 있습니다. |
예 |
|
사용자 B의 계정에 계정 수준 Webhook(사용자 B 또는 계정 관리자가 생성)가 있습니다. |
예 |
사용자 A와 사용자 B가 동일한 계정에 있으므로 계정 수준 Webhook는 해당 계정에서 트리거된 모든 이벤트에 대한 알림을 받습니다. |
사용자 B의 계정에 그룹 수준 Webhook(사용자 B 또는 계정/그룹 관리자가 생성)가 있습니다. 가정: 사용자 A, 사용자 B, 그룹 관리자가 동일한 그룹에 있습니다. |
예 |
사용자 A와 사용자 B가 동일한 그룹에 있으므로 그룹 수준 Webhook는 해당 그룹에서 트리거된 모든 이벤트에 대한 알림을 받습니다. |
사용자 B의 계정에 그룹 수준 Webhook(사용자 B 또는 계정/그룹 관리자가 생성)가 있습니다. 가정: 사용자 A와 사용자 B가 다른 그룹에 있습니다. |
아니요 |
사용자 B의 그룹 수준 Webhook는 서명자 Webhook로 간주됩니다. 사용자 A의 Webhook(리소스/사용자/그룹/계정)가 트리거됩니다. |
사용자 B에게 사용자 수준 Webhook가 있습니다. |
아니요 |
수신자로서 사용자 B의 사용자 수준 Webhook가 트리거되지 않습니다. |
사용자 C의 계정에 계정 수준 Webhook(사용자 C 또는 계정 관리자가 생성)가 있습니다. |
예 |
사용자 A와 사용자 C가 동일한 계정에 있으므로 계정 수준 Webhook는 해당 계정에서 트리거된 모든 이벤트에 대한 알림을 받습니다. |
사용자 C의 계정에 그룹 수준 Webhook(사용자 C 또는 계정/그룹 관리자가 생성)가 있습니다. 가정: 사용자 A, 사용자 C, 그룹 관리자가 동일한 그룹에 있습니다. |
예 |
사용자 A와 사용자 C가 동일한 그룹에 있으므로 그룹 수준 Webhook는 해당 그룹에서 트리거된 모든 이벤트에 대한 알림을 받습니다. |
사용자 C의 계정에 그룹 수준 Webhook(사용자 C 또는 계정/그룹 관리자가 생성)가 있습니다. 가정: 사용자 A와 사용자 C가 다른 그룹에 있습니다. |
아니요 |
사용자 C의 그룹 수준 Webhook는 비 작성자 Webhook로 간주됩니다. 사용자 A의 Webhook(리소스/사용자/그룹/계정)가 트리거됩니다. |
사용자 C에게 사용자 수준 Webhook가 있습니다. |
아니요 |
사용자 C의 사용자 수준 Webhook는 비 작성자 Webhook로 간주됩니다. |
수신 대기 서비스가 다운되었을 때 다시 시도
Webhook 대상 URL이 다운된 경우 Acrobat Sign은 JSON을 대기열에 추가하고 72시간 동안 점진적 주기로 푸시를 다시 시도합니다.
전달되지 않은 이벤트는 다시 시도 대기열에 유지되며 다음 72시간 동안 발생한 순서대로 알림을 전달하기 위해 계속 시도합니다.
알림 전달을 다시 시도하는 전략은 시도 간 시간을 두 배로 늘리는 것입니다. 1분 간격에서 시작하여 매 12시간 동안 증가하여 72시간 동안 총 15번을 다시 시도합니다.
Webhook 수신자가 72시간 이내에 응답하지 못하고 지난 7일 동안 성공적인 알림 배달이 없는 경우 Webhook은 비활성화됩니다. Webhook이 다시 활성화될 때까지 이 URL에 알림이 전송되지 않습니다.
Webhook이 비활성화되는 시점과 나중에 다시 활성화되는 시점 사이의 모든 알림은 손실됩니다.
