클라이언트 ID를 가져오고 유효성을 검사한 다음 응답 헤더에 반환하는 샘플 Javascript 코드
새로운 기능
시작하기
관리
- Admin Console 개요
- 사용자 관리
-
계정/그룹 설정
- 설정 개요
- 전역 설정
- 계정 설정
- 서명 기본 설정
- 디지털 서명
- 전자 봉인
- 디지털 신원
-
보고서 설정
- 보안 설정
- 전송 설정
- Bio-Pharma 설정
- 공증 설정
- 결제 통합
- SAML 설정
- 데이터 거버넌스
- 타임 스탬프 설정
- 외부 보관
- 계정 언어
- 이메일 설정
- echosign.com에서 adobesign.com으로 마이그레이션합니다.
- 수신자 옵션 구성
- 규정 요구 사항 지침
- 도메인 요청
- 오용 신고 링크
계약 전송, 서명 및 관리
- 수신자 옵션
- 계약 보내기
-
문서에 필드 작성
- 인앱 작성 환경
- 텍스트 태그로 폼 만들기
- Acrobat으로 폼 만들기(AcroForm)
- 필드
- 작성 FAQ
- 계약 서명
- 계약 관리
- 감사 보고서
- 보고 및 데이터 내보내기
고급 계약 기능 및 워크플로우
- 웹 양식
- 재사용 가능 템플릿
- 웹 양식 및 라이브러리 템플릿의 소유권 이전
-
Power Automate 워크플로우
- Power Automate 통합 및 포함된 권한 개요
- Power Automate 통합 활성화
- 관리 페이지의 컨텍스트별 작업
- Power Automate 사용 추적
- 새 플로우 만들기(예시)
- 플로우에 사용되는 트리거
- Acrobat Sign 외부에서 플로우 가져오기
- 플로우 관리
- 플로우 편집
- 플로우 공유
- 플로우 비활성화 또는 활성화
- 플로우 삭제
-
템플릿 사용
- 관리자만
- 계약 보관
- 웹 양식 계약 보관
- 계약 데이터 추출
- 계약 알림
- 계약 생성
- 사용자 지정 전송 워크플로우
- 사용자 및 계약 공유
다른 제품과 통합
- Salesforce용 Acrobat Sign
- Microsoft용 Acrobat Sign
- 기타 통합
- 파트너 관리 통합
- 통합 키 획득 방법
Acrobat Sign 개발자
- REST API
지원 및 문제 해결
개요
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로 알림 전달을 다시 시도합니다.
활성화하거나 비활성화하는 방법
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는 모든 이벤트를 받습니다.
수신 대기 서비스가 다운되었을 때 다시 시도
Webhook 대상 URL이 다운된 경우 Acrobat Sign은 JSON을 대기열에 추가하고 72시간 동안 점진적 주기로 푸시를 다시 시도합니다.
전달되지 않은 이벤트는 다시 시도 대기열에 유지되며 다음 72시간 동안 발생한 순서대로 알림을 전달하기 위해 계속 시도합니다.
알림 전달을 다시 시도하는 전략은 시도 간 시간을 두 배로 늘리는 것입니다. 1분 간격에서 시작하여 매 12시간 동안 증가하여 72시간 동안 총 15번을 다시 시도합니다.
Webhook 수신자가 72시간 이내에 응답하지 못하고 지난 7일 동안 성공적인 알림 배달이 없는 경우 Webhook은 비활성화됩니다. Webhook이 다시 활성화될 때까지 이 URL에 알림이 전송되지 않습니다.
Webhook이 비활성화되는 시점과 나중에 다시 활성화되는 시점 사이의 모든 알림은 손실됩니다.