Пример кода Javascript для получения идентификатора клиента, проверки и последующего возвращения в заголовке ответа
Последнее обновление
10 янв. 2024 г.
|
Также применяется к Adobe Acrobat Sign
- Интеграции Adobe Acrobat Sign
- Новые возможности
- Версии и жизненный цикл продуктов
- Acrobat Sign для Salesforce
- Установка пакета
- Настройка пакета
- Руководство пользователя
- Включение аутентификации по цифровому удостоверению
- Руководство разработчика
- Руководство по расширенной настройке
- Руководство по сопоставлению и шаблонам полей
- Руководство пользователя мобильного приложения
- Руководство по автоматизации потоков
- Руководство для Document Builder
- Настройка больших документов
- Руководство по обновлению
- Заметки о выпуске
- Часто задаваемые вопросы
- Руководство по устранению неполадок
- Дополнительные статьи
- Acrobat Sign для Microsoft
- Acrobat Sign для Microsoft 365
- Acrobat Sign для Outlook
- Acrobat Sign для Word/PowerPoint
- Acrobat Sign для Teams
- Acrobat Sign для Microsoft PowerApps и Power Automate
- Соединитель Acrobat Sign для Microsoft Search
- Acrobat Sign для Microsoft Dynamics
- Acrobat Sign для Microsoft SharePoint
- Обзор
- SharePoint On-Prem: Руководство по установке
- SharePoint On-Prem: Руководство по сопоставлению шаблонов
- SharePoint On-Prem: Руководство пользователя
- SharePoint On-Prem: Заметки о выпуске
- SharePoint Online: Руководство по установке
- SharePoint Online: Руководство по сопоставлению шаблонов
- SharePoint Online: Руководство пользователя
- SharePoint Online: Руководство по сопоставлению веб-форм
- SharePoint Online: Заметки о выпуске
- Acrobat Sign для Microsoft 365
- Acrobat Sign для ServiceNow
- Acrobat Sign для HR ServiceNow
- Acrobat Sign для SAP SuccessFactors
- Acrobat Sign для Workday
- Acrobat Sign для NetSuite
- Acrobat Sign для SugarCRM
- Acrobat Sign для VeevaVault
- Acrobat Sign для Coupa BSM Suite
- Acrobat Sign для Zapier
- Документация для разработчиков Acrobat Sign
Обзор
Веб-перехватчик — это определяемый пользователем запрос HTTPS, который запускается при возникновении события с подпиской на исходном сайте (в данном случае — Adobe Acrobat Sign).
Итак, веб-перехватчик — это служба REST, принимающая пакет или поток данных.
Веб-перехватчики предназначены для взаимодействия между службами в модели PUSH.
При запуске события с подпиской Acrobat Sign создает запрос HTTPS POST с JSON-текстом и доставляет его по указанному URL-адресу.
По сравнению с использовавшимися ранее методами обратного вызова веб-перехватчики обладают рядом преимуществ, включая следующие:
- Администраторы могут включать собственные веб-перехватчики, не привлекая службу поддержки Acrobat Sign для создания списка URL-адресов обратных вызовов.
- Веб-перехватчики лучше обеспечивают актуальность данных, эффективность коммуникации и безопасность. Не требуется регулярный опрос данных.
- Веб-перехватчики позволяют с легкостью использовать разные уровни области применения (учетная запись/группа/пользователь/ресурс).
- Веб-перехватчики — это более современное решение для API, которое упрощает настройку современных приложений.
- Для каждой области (учетная запись/группа/пользователь/ресурс) можно настроить несколько веб-перехватчиков, тогда как обратные вызовы должны быть уникальными.
- Веб-перехватчики позволяют выбирать данные для возврата, в то время как обратный вызов работает по принципу «все или ничего».
- Можно настроить, какие метаданные (только основные или подробные) может передавать веб-перехватчик.
- Поскольку пользовательский интерфейс полностью контролируется администратором, веб-перехватчики намного проще создавать, редактировать или отключать по мере необходимости.
Примечание.
Этот документ в основном посвящен пользовательскому интерфейсу веб-перехватчиков в веб-приложении Acrobat Sign (ранее Adobe Sign).
Разработчики, которым нужны подробности относительно API, могут найти информацию во следующей ссылке:
Способ применения
Прежде всего администраторам потребуется служба веб-перехватчиков, готовая принимать входящие push-уведомления от Acrobat Sign. Здесь есть множество вариантов, и веб-перехватчик будет успешно работать с любой службой, которая умеет принимать запросы POST и GET.
После запуска службы администратор Acrobat Sign может создать новый веб-перехватчик в интерфейсе веб-перехватчика меню «Учетная запись» на сайте Acrobat Sign.
Администраторы могут настроить запуск веб-перехватчика для событий документа, веб-формы (виджет) или массовой отправки (MegaSign). Шаблон библиотеки (документ библиотеки) также можно настроить через API.
Область действия веб-перехватчика может включать всю учетную запись или отдельные группы, что настраивается через интерфейс администратора. API обеспечивает большую гибкость за счет возможности выбора между диапазонами USER или RESOURCE.
Можно настраивать тип данных, передаваемых по URL-адресу, и включать такие сведения, как сведения о соглашении, информацию об участнике, сведения о документе и т. д.
После настройки и сохранения веб-перехватчика Acrobat Sign будет отправлять новый JSON-объект по указанному URL-адресу при каждом срабатывании события с подпиской. Если вы не хотите менять критерии переключающего события или полезную нагрузку JSON, никаких манипуляций с веб-перехватчиком выполнять не нужно.
Проверка намерения для URL-адреса веб-перехватчика
Перед завершением регистрации веб-перехватчика Acrobat Sign проверяет, действительно ли указанный в запросе на регистрацию URL-адрес веб-перехватчика предназначен для получения уведомлений. Поэтому когда Acrobat Sign получает запрос на регистрацию нового веб-перехватчика, он сначала отправляет запрос проверки по URL-адресу веб-перехватчика. Он представляет собой запрос HTTPS GET, отправляемый на URL-адрес веб-перехватчика. Этот запрос имеет собственный HTTP-заголовок X-AdobeSign-ClientId. Значение в этом заголовке установлено для идентификатора клиента API-приложения (идентификатора приложения), которое запрашивает создание/регистрацию веб-перехватчика. Для успешной регистрации веб-перехватчика его URL-адрес должен ответить на этот запрос проверки, используя код ответа 2XX, А ТАКЖЕ должен отправить одно и то же значение идентификатора клиента одним из следующих двух способов:
- В заголовке ответа X-AdobeSign-ClientId. Это тот же заголовок, который передан в запросе и должен быть возвращен при ответе.
- Либо в тексте ответа JSON с ключом xAdobeSignClientId, значением которого является тот же идентификатор клиента, который отправлен в запросе.
Веб-перехватчик будет зарегистрирован только при успешном ответе (код ответа 2XX) и после проверки идентификатора клиента либо в заголовке, либо в тексте ответа. Цель этого запроса проверки — убедиться в том, что URL-адрес веб-перехватчика действительно готов получать уведомления на указанный URL-адрес. Если вы случайно введете неверный URL-адрес, он не будет правильно отвечать на запрос проверки намерения, и Acrobat Sign не станет отправлять уведомления на этот URL-адрес. URL-адрес веб-перехватчика также может подтвердить, что уведомления будут получаться только через веб-перехватчики, зарегистрированные конкретным приложением. Это выполняется путем проверки идентификатора клиента приложения, переданного в заголовке X-AdobeSign-ClientId. Если URL-адрес веб-перехватчика не распознает идентификатор клиента, он НЕ БУДЕТ отсылать ответный код об успешном выполнении операции, а Acrobat Sign позаботится о том, чтобы этот URL-адрес не был зарегистрирован в качестве веб-перехватчика.
Проверка вызова URL-адреса веб-перехватчика будет выполняться при следующих сценариях:
- Регистрация веб-перехватчика. Веб-перехватчик не будет создан, если проверка URL-адреса веб-перехватчика не завершена.
- Обновление веб-перехватчика с НЕАКТИВНОГО на АКТИВНЫЙ. Если проверка URL-адреса веб-перехватчика не завершится, состояние веб-перехватчика не будет изменено на АКТИВНОЕ.
Как ответить на уведомление веб-перехватчика
Acrobat Sign выполняет неявную проверку намерений в каждом запросе уведомления веб-перехватчика, отправляемом на его URL-адрес. Таким образом, каждый HTTPS-запрос уведомления веб-перехватчика также содержит настраиваемый HTTP-заголовок X-AdobeSign-ClientId. Значением в этом заголовке является идентификатор клиента (идентификатор приложения) того приложения, которое создало веб-перехватчик. Уведомление веб-перехватчика будет считаться доставленным, только если будет возвращен успешный ответ (код ответа 2XX), а идентификатор клиента будет отправлен либо в заголовке HTTP (X-AdobeSign-ClientId), либо в тексте ответа JSON с ключом xAdobeSignClientId и значением идентификатора клиента. В противном случае мы будем повторять попытки доставить уведомление на URL-адрес веб-перехватчика, пока не будет исчерпано заданное максимальное число попыток.
Как было сказано выше, заголовок 'X-AdobeSign-ClientId' , который включается в каждый запрос уведомления от Sign, и значение этого заголовка (идентификатор клиента) должны возвращаться при ответе одним из двух способов:
1. Заголовок HTTP X-AdobeSign-ClientId, значением которого является идентификатор клиента.
|
|
|---|
|
// Запись идентификатора клиента var clientid = request.headers['X-ADOBESIGN-CLIENTID'];
// Проверка if (clientid ==="BGBQIIE7H253K6") // Заменить BGBQIIE7H253K6 идентификатором клиента приложения на момент создания веб-перехватчика { // Возврат в заголовке ответа response.headers['X-AdobeSign-ClientId'] = clientid; response.status = 200; // Значение по умолчанию } |
|
Пример кода PHP для получения идентификатора клиента, проверки и последующего возвращения в заголовке ответа |
|---|
|
<?php // Запись идентификатора клиента $clientid = $_SERVER['HTTP_X_ADOBESIGN_CLIENTID']; // Проверка if($clientid == "BGBQIIE7H253K6") // Заменить BGBQIIE7H253K6 идентификатором клиента приложения на момент создания веб-перехватчика { // Возврат в заголовке ответа header("X-AdobeSign-ClientId:$clientid"); header("HTTP/1.1 200 OK"); // Значение по умолчанию } ?> |
2. Тело ответа в формате JSON с ключом xAdobeSignClientId и значением того же идентификатора клиента
|
Пример кода Javascript для получения идентификатора клиента, проверки и последующего возвращения в теле ответа |
|---|
|
// Запись идентификатора клиента var clientid = request.headers['X-ADOBESIGN-CLIENTID'];
// Проверка if (clientid ==="BGBQIIE7H253K6") // Заменить BGBQIIE7H253K6 идентификатором клиента приложения на момент создания веб-перехватчика { var responseBody = { "xAdobeSignClientId" : clientid // Возвращает идентификатор клиента в теле }; response.headers['Content-Type'] = 'application/json'; response.body = responseBody; response.status = 200; } |
|
Пример кода PHP для получения идентификатора клиента, проверки и последующего возвращения в теле ответа |
|---|
|
<?php // Запись идентификатора клиента $clientid = $_SERVER['HTTP_X_ADOBESIGN_CLIENTID']; // Проверка if($clientid == "BGBQIIE7H253K6") // Заменить BGBQIIE7H253K6 идентификатором клиента приложения на момент создания веб-перехватчика { // Возврат в теле ответа header("Content-Type: application/json"); $body = array('xAdobeSignClientId' => $clientid); echo json_encode($body); header("HTTP/1.1 200 OK"); // Значение по умолчанию } ?> |
|
Пример тела ответа в формате JSON |
|---|
|
{ "xAdobeSignClientId": "BGBQIIE7H253K6" } |
Необходимые требования
Вам потребуется следующее:
- Учетная запись Microsoft с лицензией на создание приложений Функций Azure;
- Существующее приложение Функций Azure, которое можно создать с помощью https://docs.microsoft.com/en-us/azure/azure-functions/functions-create-first-azure-function;
- Базовые знания Javascript, чтобы вы могли понимать и писать код на предпочитаемом вами языке программирования.
Процедура создания инициирующего события функций Azure, которое служит веб-перехватчиком Acrobat Sign
Для создания функции инициирующего события HTTP на языке Javascript выполните следующее:
1. Войдите со своей учетной записью Microsoft https://portal.azure.com;
2. Откройте приложение Функций Azure, отображаемое на вкладке «Приложения-функции».
При этом откроется ваш список приложений Функций Azure:
3. Выберите приложение, в котором вы хотите создать новую функцию.
4. Нажмите кнопку «Создать» (+), чтобы создать новую функцию Azure
5. Выберите сценарий Webhook + API и язык Javascript .
6. Нажмите Создать функцию
Вы создали новую функцию, способную обрабатывать входящий запрос API.
Добавление логики для регистрации веб-перехватчика Acrobat Sign
Перед тем, как успешно завершить регистрацию веб-перехватчика, Acrobat Sign проверяет, действительно ли указанный в запросе на регистрацию URL-адрес веб-перехватчика предназначен для получения уведомлений. С этой целью при получении нового запроса на регистрацию веб-перехватчика Acrobat Sign сначала отправляет запрос на проверку URL-адреса веб-перехватчика. Этот запрос на проверку представляет собой запрос HTTPS GET, отправленный на URL-адрес веб-перехватчика с настраиваемым заголовком HTTP X-AdobeSign-ClientId. Значением в этом заголовке является идентификатор клиента того приложения API, которое запрашивает создание и (или) регистрацию веб-перехватчика. Для успешной регистрации веб-перехватчика его URL-адрес должен ответить на этот запрос на проверку, используя код ответа 2XX, А ТАКЖЕ должен отправить одно и то же значение идентификатора клиента одним из следующих двух способов:
У вас есть два варианта действий.
Вариант 1. Передать идентификатор клиента в X-AdobeSign-ClientId в качестве заголовка ответа
Передайте X-AdobeSign-ClientId в заголовке ответа. Это тот же заголовок, который был передан в запросе и должен быть возвращен при ответе.
Замените файл Index.js следующим:
module.exports = function (context, req) {
var clientId = req.headers['x-adobesign-clientid'];
// Проверка подлинности входящего идентификатора клиента
if (clientId === '123XXX456') {
context.res = {
// status: 200, /* По умолчанию: 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
В теле ответа JSON с ключом xAdobeSignClientId, значением которого является тот же идентификатор клиента, который был отправлен в заголовке запроса.
Замените файл Index.js следующим:
module.exports = function (context, req) {
var clientId = req.headers['x-adobesign-clientid'];
// Проверка подлинности входящего идентификатора клиента
if (clientId === '123XXX456') {
context.res = {
// status: 200, /* По умолчанию: 200 */ // любой ответ 2XX является приемлемым
body: {
'xAdobeSignClientId' : clientId
},
headers : {
'Content-Type' : 'application/json'
}
};
}
else {
context.res = {
status: 400,
body: "Opps!! Illegitimate Call identified"
};
}
context.done();
};
Проверьте поведение, выполнив имитацию запроса:
1. Нажмите кнопку Тест в правом углу;
2. Смоделируйте фиктивный запрос.
Обратите внимание, что такое же поведение для clientID ожидается, когда URL-адрес веб-перехватчика получает уведомления POST.
Готовность к использованию
После проверки поведения URL-адрес веб-перехватчика действует по стандартам Acrobat Sign. В дальнейшем вы можете обновить пользовательскую логику в соответствии с вашими требованиями.
Получение URL-адреса функции
- Нажмите Получить URL-адрес функции
Скопируйте URL-адрес и используйте его для создания веб-перехватчиков в Acrobat Sign.
Создание функции AWS Lambda
Чтобы создать функцию AWS Lambda, перейдите к Панели управления AWS и выберите в списке служб AWS Lambda.
- Выберите «Создать функцию Lambda» с помощью варианта «Автор с нуля».
- На странице настроек функции введите имя функции lambdaWebhooks и выберите Node.js 4.3 в качестве среды выполнения
- Для параметра Роль выберите существующую роль или создайте новую на основе шаблона.
- Если вы выбрали Создать новую роль из шаблона(-ов), введите имя роли (например, role-lamda) и выберите Разрешения Simple Microservices из списка Шаблоны политик.
- Нажмите кнопку Создать функцию.
- На странице новой лямбда-функции AWS выберите вариант Изменить встроенный код для параметра Тип ввода кода и сохраните значение обработчика index.handler.
- Добавление логики для регистрации веб-перехватчика Acrobat Sign
Перед тем, как успешно завершить регистрацию веб-перехватчика, Acrobat Sign проверяет, действительно ли указанный в запросе на регистрацию URL-адрес веб-перехватчика предназначен для получения уведомлений. С этой целью при получении нового запроса на регистрацию веб-перехватчика Acrobat Sign сначала отправляет запрос на проверку URL-адреса веб-перехватчика. Этот запрос на проверку представляет собой запрос HTTPS GET, отправленный на URL-адрес веб-перехватчика с настраиваемым заголовком HTTP X-AdobeSign-ClientId. Значением в этом заголовке является идентификатор клиента того приложения API, которое запрашивает создание и (или) регистрацию веб-перехватчика. Для успешной регистрации веб-перехватчика его URL-адрес должен ответить на этот запрос на проверку, используя код ответа 2XX, А ТАКЖЕ должен отправить одно и то же значение идентификатора клиента одним из следующих двух способов: Обратите внимание, что такое же поведение для clientID ожидается, когда URL-адрес веб-перехватчика получает уведомления POST.
Действуйте по одному из следующих сценариев:
Сценарий 1. Передача идентификатора клиента в заголовке ответа X-AdobeSign-ClientId
- Передайте X-AdobeSign-ClientId в заголовке ответа. Это тот же заголовок, который был передан в запросе и должен быть возвращен при ответе.
Фрагмент кода
В файле index.js замените автоматически сгенерированный фрагмент кода следующим:
- Передайте X-AdobeSign-ClientId в заголовке ответа. Это тот же заголовок, который был передан в запросе и должен быть возвращен при ответе.
|
Пример кода JS для получения идентификатора клиента, проверки и последующего возвращения в заголовке ответа |
|---|
|
exports.handler = function index(event, context, callback) { // Запись идентификатора клиента var clientid = event.headers['X-AdobeSign-ClientId'];
// Проверка if (clientid =="BGBQIIE7H253K6")) // Заменить BGBQIIE7H253K6 идентификатором клиента приложения на момент создания веб-перехватчика { var response = { statusCode: 200, headers: { "X-AdobeSign-ClientId": clientid } }; callback(null,response); } else { callback("Oops!! illegitimate call"); } } |
Сценарий 2. Передача идентификатора клиента в теле ответа с ключом xAdobeSignClientId
В теле ответа JSON с ключом xAdobeSignClientId, значением которого является тот же идентификатор клиента, который был отправлен в заголовке запроса.
Фрагмент кода
Замените файл Index.js следующим:
|
Пример кода JS для получения идентификатора клиента, проверки и последующего возвращения в заголовке ответа |
|---|
|
exports.handler = function index(event, context, callback) { // Запись идентификатора клиента var clientid = event.headers['X-AdobeSign-ClientId'];
// Проверка if (clientid =="BGBQIIE7H253K6")) // Заменить BGBQIIE7H253K6 идентификатором клиента приложения на момент создания веб-перехватчика { var responseBody = { xAdobeSignClientId : clientid };
var response = { statusCode: 200, body: JSON.stringify(responseBody) };
callback(null,response); } else { callback("Opps!! illegitimate call"); } } |
- Сохраните функцию: Лямбда-функция создана, и мы почти готовы использовать ее в веб-перехватчике в режиме реального времени.
Настройка шлюза API AWS
Чтобы сделать эту лямбда-функцию общедоступной через метод HTTP, нам нужно настроить шлюз API AWS, используя созданную выше функцию в качестве серверной части API.
В консоли управления AWS выберите в списке сервисов AWS шлюз API и нажмите кнопку Создать API.
- На странице Создание нового API выберите Новый API и введите webhooks в параметре Имя API.
- Нажмите кнопку Создать API.
- Раскройте список Действия и выберите в нем Создать ресурс.
- Поставьте отметку напротив варианта Настроить в качестве ресурса прокси, введите validate в поле Имя ресурса и {proxy+} в поле Путь к ресурсу.
- Оставьте пустым поле для отметки напротив варианта Включить CORS шлюза API и нажмите кнопку Создать ресурс.
- Оставьте прокси-сервер функции Lambda выбранным в качестве типа интеграции и выберите регион, в котором вы создали свою функцию Lambda, из раскрывающегося списка регионов Lambda (это может быть тот же регион, где вы создаете шлюз API).
- Укажите validate в качестве Функции Lambda и нажмите кнопку Сохранить.
- Во всплывающем окне Добавить разрешение в функцию Lambda нажмите ОК.
Если все перечисленные выше шаги выполнены успешно, вы увидите что-то подобное:
Развертывание API
Следующий этап — развертывание этого API, чтобы подготовить его к использованию.
- В раскрывающемся списке Действия выберите Развернуть API.
- Выберите [Новый этап] в разделе Этап развертывания и введите prod (или любое другое понятное название) в поле Название этапа.
- Нажмите кнопку Развернуть.
Теперь API готов к использованию, и вы можете найти URL-адрес для его вызова в синем окошке, как показано ниже.
Запишите этот URL-адрес, так как вам нужно будет ввести его в качестве URL-адреса веб-перехватчика в реальном времени.
Готовность к использованию
Готово. Используйте указанный выше URL-адрес с постфиксом «/{nodeJSfunctionName}» в качестве URL-адреса веб-перехватчика в запросе API POST /webhooks. После проверки поведения URL-адрес веб-перехватчика действует по стандартам
Acrobat Sign. В дальнейшем вы можете обновить пользовательскую логику в соответствии с вашими требованиями.
Параметры конфигурации
Для настройки веб-перехватчика нужно определить пять элементов:
- Имя: желательно выбрать удобное имя, которое могут легко понять другие администраторы.
- Область: насколько широк диапазон действия веб-перехватчика? В интерфейсе доступны «Учетная запись» и «Группа».
- API поддерживает области «Учетная запись», «Группа», «Пользователь» и «Ресурс».
- Можно определить только одну область на один веб-перехватчик.
- URL-адрес: целевой URL-адрес, на который приложение Acrobat Sign передало полезные данные JSON.
- События: факторы, вызывающие создание JSON в Acrobat Sign и его передачу на URL-адрес.
- Каждое событие создает различный набор полезных данных для переключающего события.
- В один веб-перехватчик можно включить несколько событий .
- Параметры уведомления: параметры уведомления определяют разделы полезных данных События в формате JSON, что позволяет выбрать только важные разделы из События для конкретного веб-перехватчика (то есть сократить объем ненужных данных, передаваемых на URL-адрес).
После окончания определения веб-перехватчика нажмите Сохранить, и новый веб-перехватчик немедленно начнет реагировать на переключающие события.
Примечание.
Настройте URL-адрес веб-перехватчика, чтобы он отвечал на запросы на проверку и уведомления о веб-перехватчике в соответствии с описанным выше протоколом проверки. Идентификатор клиента (идентификатор приложения), который будет отправлен на веб-перехватчики, созданные из веб-приложения Acrobat Sign, — UB7E5BXCXY.
Области применения
- Учетная запись: все события с подпиской в учетной записи приводят к отправке push-уведомлений.
- Администраторы учетных записей имеют право просматривать все веб-перехватчики, определенные для учетной записи и всех ее групп.
- Группа: все события с подпиской в группе приводят к отправке push-уведомления. ВНИМАНИЕ: веб-перехватчики с областью групп существуют только для одной группы.
- Администраторы групп видят только веб-перехватчики, ассоциированные с конкретной группой. Они не будут видеть веб-перехватчики на уровне учетной записи или привязанные к другим группам.
- Учетные записи, для которых включена поддержка пользователей в нескольких группах, будут видеть параметр для настройки группы, к которой нужно применить область.
- Учетная запись пользователя: все события учетной записи пользователя, на которые оформлена подписка, приводят к отправке push-уведомлений. Веб-перехватчики на уровне пользователя можно создать только через API.
- Веб-перехватчик на уровне ресурса: создается для конкретного ресурса. События, относящиеся к этому ресурсу, будут отправляться на URL-адрес веб-перехватчика. Веб-перехватчики на уровне ресурса можно создать только через API.
URL-адрес
URL-адрес веб-перехватчика — это сервер, который прослушивает входящие уведомления HTTPS POST, отправляемые при наступлении событий.
Этот URL-адрес нужен для подписки веб-перехватчика на события.
- Клиент должен предоставлять URL-адрес HTTPS, на который Acrobat Sign может отправлять сообщения POST. Этот URL-адрес должен быть доступен в интернете.
- Например, URI-адреса 127.0.0.1 и localhost работать не будут.
- Конечные точки URL-адреса должны прослушивать порты 443 или 8443 (решение клиента при определении URL-адреса для обратного вызова).
- Убедитесь, что веб-перехватчик поддерживает запросы POST для уведомлений о входящих событиях и запросы GET для запросов на проверку.
- URL-адрес не должен блокироваться брандмауэром.
Ниже представлены события, которые приводят к отправке push-уведомлений на URL-адрес веб-перехватчика, сгруппированные по объекту и перечисленные в порядке, указанном в пользовательском интерфейсе.
Значение слева — это значение, которое можно видеть в пользовательском интерфейсе Acrobat Sign. Значение справа — это название веб-перехватчика в API.
Подробная информация о веб-перехватчиках и полезных данных представлена в Руководстве разработчика Acrobat Sign.
Соглашения:
| Элемент UI | Название веб-перехватчика |
| Все события соглашения | AGREEMENT_ALL |
| Соглашение создано | AGREEMENT_CREATED |
| Соглашение отправлено | AGREEMENT_ACTION_REQUESTED |
| Участник соглашения выполнил действие | AGREEMENT_ACTION_COMPLETED |
| Процесс работы с соглашением завершен | AGREEMENT_WORKFLOW_COMPLETED |
| Срок действия соглашения истек | AGREEMENT_EXPIRED |
| Соглашение удалено | AGREEMENT_DOCUMENTS_DELETED |
| Соглашение отменено | AGREEMENT_RECALLED |
| Соглашение отклонено | AGREEMENT_REJECTED |
| Доступ к соглашению предоставлен | AGREEMENT_SHARED |
| Соглашение передано | AGREEMENT_ACTION_DELEGATED |
| Участник соглашения заменен | AGREEMENT_ACTION_REPLACED_SIGNER |
| Соглашение изменено | AGREEMENT_MODIFIED |
| Изменение соглашения подтверждено | AGREEMENT_USER_ACK_AGREEMENT_MODIFIED |
| Сообщение электронной почты с соглашением просмотрено | AGREEMENT_EMAIL_VIEWED |
| Сообщение электронной почты с соглашением возвращено | AGREEMENT_EMAIL_BOUNCED |
| Не удалось создать соглашение | AGREEMENT_AUTO_CANCELLED_CONVERSION_PROBLEM |
| Соглашение синхронизировано после события в автономном режиме | AGREEMENT_OFFLINE_SYNC |
| Соглашение загружено отправителем | AGREEMENT_UPLOADED_BY_SENDER |
| Соглашение помещено в хранилище | AGREEMENT_VAULTED |
| Участник соглашения прошел аутентификацию с помощью учетной записи в социальных сетях | AGREEMENT_WEB_IDENTITY_AUTHENTICATED |
| Участник соглашения прошел аутентификацию на основе знаний | AGREEMENT_KBA_AUTHENTICATED |
| Напоминание о документе отправлено | AGREEMENT_REMINDER_SENT |
| Лицо, пописывающее соглашение, изменено другим лицом | AGREEMENT_SIGNER_NAME_CHANGED_BY_SIGNER |
| Веб-перехватчики документа доступны только через API | |
| Н/П | AGREEMENT_EXPIRATION_UPDATED |
| Н/П |
AGREEMENT_READY_TO_NOTARIZE |
| Н/П |
AGREEMENT_READY_TO_VAULT |
Пакетная отправка:
| Элемент UI | Название веб-перехватчика |
| Все события пакетной отправки | MEGASIGN_ALL |
| Пакетная отправка создана |
MEGASIGN_CREATED |
| Общий доступ к пакетной отправке предоставлен |
MEGASIGN_SHARED |
| Пакетная отправка отозвана |
MEGASIGN_RECALLED |
Веб-формы:
| Элемент UI | Название веб-перехватчика |
| Все события веб-формы | WIDGET_ALL |
| Веб-форма создана |
WIDGET_CREATED |
| Веб-форма включена |
WIDGET_ENABLED |
| Веб-форма отключена |
WIDGET_DISABLED |
| Веб-форма изменена |
WIDGET_MODIFIED |
| Предоставлен общий доступ к веб-форме |
WIDGET_SHARED |
| Не удалось создать веб-форму |
WIDGET_AUTO_CANCELLED_CONVERSION_PROBLEM |
Шаблоны библиотеки (только API):
| Элемент UI | Название веб-перехватчика |
| Н/П | LIBRARY_DOCUMENT_ALL |
| Н/П | LIBRARY_DOCUMENT_CREATED |
| Н/П | LIBRARY_DOCUMENT_AUTO_CANCELLED_CONVERSION_PROBLEM |
| Н/П | LIBRARY_DOCUMENT_MODIFIED |
Параметры уведомлений
Параметры уведомлений позволяют настраивать полезные данные JSON только для определенных элементов события.
Например, в событии Участник соглашения заменен вам могут понадобиться только Сведения о соглашении и Информация об участнике соглашения, а Сведения о соглашении вы можете исключить, что позволит сократить общий объем данных, передаваемых на URL-адрес вашего веб-перехватчика.
- Соглашение
- Сведения о соглашении: подробная информация о соглашении, основанная на его состоянии и времени события-триггера.
- Сведения о документах соглашения: включает любую информацию о документах, созданную в результате события.
- Сведения об участнике соглашения: включает любую информацию об участниках, созданную в результате события.
- Подписанный документ соглашения: представляет собой подписанный PDF-файл.
- Применяется к событиям Процесс работы с соглашением завершен и Все события соглашений.
- Пакетная отправка
- Сведения о пакетной отправке: подробная информация об объекте Пакетной отправки, который вызвал срабатывание события.
- Веб-форма
- Сведения о виджете: подробная информация о веб-форме, которая активировала событие.
- Сведения о документах виджета: информация о документах, связанных с шаблоном веб-формы.
- Сведения об участнике виджета: информация об участниках, работающих в шаблоне веб-формы.
Двусторонняя аутентификация по протоколу SSL
Двусторонний протокол SSL, часто называемый Client-Side SSL или взаимный TLS, — это такой протокол SSL, в котором как сервер, так и клиент (веб-браузер) для своей идентификации представляют сертификаты.
Администраторы учетных записей могут настроить сертификат на стороне клиента на странице Параметры безопасности.
Acrobat Sign проверяет сертификаты SSL при доставке полезных данных на URL-адрес веб-перехватчика Веб-перехватчики, не выполнившие проверку сертификата SSL, не могут успешно доставлять полезные данные JSON.
Используйте двусторонний протокол SSL для аутентификации клиента (Acrobat Sign) и службы прослушивания, чтобы гарантировать, что только Acrobat Sign сможет получить доступ к URL-адресу веб-перехватчика.
Если веб-перехватчик создан партнерским приложением, при создании обратных вызовов он будет использовать для идентификации клиентский сертификат (если имеется) из учетной записи партнерского приложения.
Ниже приведены наиболее распространенные вопросы как для процесса проверки веб-сервера, так и для проверки сертификации клиента.
Проверка веб-сервера
Во время регистрации веб-перехватчика Acrobat Sign проверяет URL-адрес сервера веб-перехватчика.
Клиенты не смогут зарегистрировать веб-перехватчик, если подключение к URL-адресу обратного вызова веб-перехватчика не может быть выполнено из Acrobat Sign.
Нет.
В качестве URL-адреса обратного вызова веб-перехватчика допускается только HTTPS на порте 443 или 8443.
Acrobat Sign блокирует исходящий трафик HTTPS на все другие порты.
Для проверки сертификата рекомендуется использовать Инструмент DigiCert® для диагностики установки SSL.
Введите только имя узла, например: www.digicert.com
Наиболее распространенные проблемы:
- Проблема: использование ненадежного ЦС или самозаверяющего сертификата
Решение: использовать общий сертификат SSL, выданный ЦС, для сервера обратного вызова веб-перехватчика.
- Проблема: сервер не отправляет промежуточный сертификат
Решение: установить промежуточные сертификаты на сервере обратного вызова веб-перехватчика.
См. https://www.digicert.com/kb/ssl-certificate-installation.htm для получения подробной информации.
Проверка сертификата клиента
Чтобы настроить двусторонний SSL для веб-перехватчика, администратор должен загрузить файл .p12 (или .pfx), содержащий секретный ключ. Файл надежно хранится в учетной записи клиента, и администратор имеет полный контроль, чтобы удалить его в любое время.
В двусторонней настройке веб-перехватчика Acrobat Sign является вызывающей стороной/клиентом, и ему требуется секретный ключ, чтобы подтвердить, что вызов выполняется с помощью Acrobat Sign от имени учетной записи клиента.
-
Проверить включение двустороннего SSL
Двусторонний SSL должен быть включен на сервере обратного вызова веб-перехватчика.
При помощи любого веб-браузера подключитесь к URL-адресу обратного вызова веб-перехватчика. Ожидаемый результат:
400, неверный запрос Требуемый сертификат SSL не отправлен
Это означает, что сервер ожидает, что клиент отправит сертификаты клиента (т.е. для сервера включен двусторонний SSL).
Если вы не видите приведенное выше сообщение, двусторонний SSL не включен.
Примечание.Можно использовать Postman и выполнить запрос POST по URL-адресу обратного вызова веб-перехватчика. В этом случае должен быть получен аналогичный результат.
-
Учетные данные клиента могут быть либо самозаверяющим сертификатом, либо сертификатом, выданным ЦС. Однако они должны как минимум соответствовать следующим расширениям X.509 v3:
Расширение X.509 v3
Значение
ExtendedKeyUsage
clientAuth (идентификатор объекта: 1.3.6.1.5.5.7.3.2)
KeyUsage
digitalSignature
Сертификат клиента должен являться файлом PKCS12 с расширением .p12 или .pfx и должен включать как сертификат клиента (чтобы сервер мог проверить личность клиента), так и секретный ключ клиента (чтобы клиент мог подписывать сообщения цифровой подписью для проверки сервером во время рукопожатия SSL).
Использовать команду openssl для проверки файла p12 (pfx):
openssl pkcs12 -info -in outfile.p12
Следует запросить кодовую фразу для секретного ключа. Выходные данные должны содержать оба сертификата, а также зашифрованный секретный ключ, например:
Bag Attributes localKeyID: 9D BD 22 80 E7 B2 B7 58 9E AE C8 42 71 F0 39 E1 E7 2B 57 DB subject=/C=US/ST=California/L=San Jose/O=Adobe Inc./CN=sp.adobesignpreview.com issuer=/C=US/O=DigiCert Inc/CN=DigiCert TLS RSA SHA256 2020 CA1 -----BEGIN CERTIFICATE----- MIIGwDCCBaigAwIBAgIQAhJSKDdyQZjlbYO5MJAYOTANBgkqhkiG9w0BAQsFADBP MQswCQYDVQQGEwJVUzEVMBMGA1UEChMMRGlnaUNlcnQgSW5jMSkwJwYDVQQDEyBE ... JAKQLQ== -----END CERTIFICATE----- Bag Attributes: <No Attributes> subject=/C=US/O=DigiCert Inc/CN=DigiCert TLS RSA SHA256 2020 CA1 issuer=/C=US/O=DigiCert Inc/OU=www.digicert.com/CN=DigiCert Global Root CA -----BEGIN CERTIFICATE----- MIIEvjCCA6agAwIBAgIQBtjZBNVYQ0b2ii+nVCJ+xDANBgkqhkiG9w0BAQsFADBh MQswCQYDVQQGEwJVUzEVMBMGA1UEChMMRGlnaUNlcnQgSW5jMRkwFwYDVQQLExB3 ... -----END CERTIFICATE----- Bag Attributes localKeyID: 9D BD 22 80 E7 B2 B7 58 9E AE C8 42 71 F0 39 E1 E7 2B 57 DB Key Attributes: <No Attributes> -----BEGIN ENCRYPTED PRIVATE KEY----- MIIFDjBABgkqhkiG9w0BBQ0wMzAbBgkqhkiG9w0BBQwwDgQI7eNh2qlsLPkCAggA ... FHE= -----END ENCRYPTED PRIVATE KEY-----Сертификаты должны как минимум включать сертификат конечного субъекта и промежуточные сертификаты. В идеальном случае он также должен включать корневой сертификат ЦС.
Оповещение:Убедитесь, что файл .p12 или .pfx защищен кодовой фразой.
-
Создайте самозаверяющий сертификат клиента (необязательно)
Сертификаты клиента могут быть выданы ЦС или быть самозаверяющими, в зависимости от конкретных потребностей.
Чтобы создать самозаверяющий сертификат клиента, используйте следующий команду openssl:
openssl req -newkey rsa:4096 -keyform PEM -keyout ca.key -x509 -days 3650 -outform PEM -out ca.cer
Внимание.Соблюдайте конфиденциальность полученных файлов, так как это ваши самозаверяющие сертификаты ЦС.
Затем создайте клиентский файл .p12:
- Создайте секретный ключ для клиента SSL:
openssl genrsa -out client.key 2048
- Используйте секретный ключ клиента для создания запроса сертификата:
openssl req -new -key client.key -out client.req
- Выдайте сертификат клиента, используя запрос сертификата и сертификат/ключ ЦС:
openssl x509 -req -in client.req -CA ca.cer -CAkey ca.key -set_serial 101 -extensions client -days 365 -outform PEM -out client.cer
- Преобразуйте сертификат клиента и секретный ключ в формат pkcs#12 для использования в браузерах:
openssl pkcs12 -export -inkey client.key -in client.cer -out client.p12
- Удалите секретный ключ клиента, сертификат клиента и файлы запроса клиента, поскольку в pkcs12 уже есть все необходимое.
rm client.key client.cer client.req
- Создайте секретный ключ для клиента SSL:
-
- Используйте Postman, чтобы загрузить файл PFX клиента в разделе Настройки > Сертификаты.
- Выберите Добавить сертификат, чтобы добавить сертификат клиента.
- Настройте HTTP-заголовок для x-adobesign-clientid:
После настройки отправьте запрос POST на URL-адрес обратного вызова веб-перехватчика.
Должен быть получен ответ 200 .
-
Почему Acrobat Sign отклоняет файл PFX даже после его проверки с помощью Postman?
Если вы следовали описанному выше процессу проверки файла pfx, но Acrobat Sign по-прежнему отклоняет файл pfx, вероятно, файл был создан с помощью инструмента Microsoft, который может формировать нестандартный файл PKCS12.
В этом случае используйте приведенные ниже команды openssl для извлечения сертификатов и секретного ключа из файла pfx, а затем создайте правильно отформатированный файл PKCS12:
// Extract certificates and private key from pfx file openssl pkcs12 -info -in microsoftclientssl.pfx -passin pass:"" -out clientcert.crt -nokeys openssl pkcs12 -info -in microsoftclientssl.pfx -passin pass:"" -out clientcert.key -nodes -nocerts // Create new PKCS12 file openssl pkcs12 -export -inkey clientcert.key -in clientcert.crt -out clientcert.pfx
Как включить или отключить функцию
Доступ к функции веб-перехватчиков для учетных записей корпоративного плана открыт по умолчанию.
Администраторы на уровне группы могут создавать и контролировать веб-перехватчики, которые работают только в пределах их групп.
Доступ к странице веб-перехватчиков можно найти в левой части меню администратора: Учетная запись > Веб-перехватчики
Активация веб-перехватчика
При первом создании веб-перехватчика он создается со статусом Активный.
На странице веб-перехватчиков в Acrobat Sign вы увидите активные веб-перехватчики по умолчанию.
Для активации неактивного веб-перехватчика:
- Щелкните на иконке Параметры (три горизонтальные линии) справа от строки заголовка веб-перехватчиков Показать все веб-перехватчики
- Щелкните один раз на неактивном веб-перехватчике, чтобы его выбрать.
- Этим действием вы раскроете параметры веб-перехватчика прямо под строкой заголовка.
- Нажмите кнопку Активировать
Активный веб-перехватчик начнет отправлять данные на целевой URL, как только произойдет следующее событие.
Отключение веб-перехватчика
Для отключения веб-перехватчика нужно выполнить следующие действия:
- Перейдите на страницу Веб-перехватчики.
- Щелкните один раз на веб-перехватчике, который хотите отключить.
- Нажмите Отключить в меню под строкой заголовка.
- После этого его статус отобразится как неактивный
Просмотр и изменение веб-перехватчика
Веб-перехватчики можно изменять и сохранять в любое время, причем новые параметры вступают в силу сразу после их сохранения.
Изменять можно только События и Параметры уведомлений.
Если нужно изменить Имя, Область или URL-адрес, придется создать новый веб-перехватчик.
Для изменения параметров веб-перехватчика:
- Перейдите на страницу Веб-перехватчики.
- Щелкните один раз на веб-перехватчике, который хотите изменить
- Щелкните Просмотр/Изменение под строкой заголовка
- Внесите нужные изменения и нажмите Сохранить
Удаление веб-перехватчика
Веб-перехватчик можно удалить в любой момент.
Удаление веб-перехватчика уничтожает его в системе, поэтому восстановить его будет невозможно.
Веб-перехватчики не нужно отключать перед удалением.
Для удаления веб-перехватчика:
- Перейдите на страницу веб-перехватчиков
- Выберите веб-перехватчик, который хотите удалить, щелкнув на нем один раз.
- Щелкните Удалить под строкой заголовка
- Вам будет предложено подтвердить удаление. Нажмите ОК.
Рекомендации
- Подпишитесь на конкретные события, чтобы ограничить количество запросов HTTPS к серверу. Чем более конкретны ваши веб-перехватчики, тем меньший объем информации будет необходимо обрабатывать.
- Устойчивость к дублированию. Если у вас больше одного приложения, использующего один и тот же URL-адрес веб-перехватчика, и с каждым приложением сопоставлен один и тот же пользователь, одно и то же событие будет отправляться на ваш веб-перехватчик несколько раз (по одному разу для каждого приложения). В некоторых случаях ваш веб-перехватчик может получать дубликаты событий. Ваше приложение веб-перехватчика должно относиться к этому спокойно и выполнять дедупликацию по идентификатору события.
- Быстрый ответ веб-перехватчику. У приложения есть всего пять секунд для ответа на запрос веб-перехватчика. В случае запроса на проверку это не проблема, поскольку вашему приложению не нужно выполнять никакой реальной работы для ответа. В случае запросов уведомления вашему приложению понадобится выполнить ряд действий для ответа на запрос. Рекомендуется работать либо в отдельной ветке или асинхронно при помощи очереди, чтобы ответ отправлялся в течение 5 секунд.
- Управление одновременным выполнением. Когда пользователь быстро вносит несколько изменений, приложение может почти одновременно получить несколько уведомлений о действиях одного пользователя. Если вы не будете следить за параллельным доступом, ваше приложение может обрабатывать одни и те же изменения для каждого пользователя несколько раз. Чтобы пользоваться преимуществами веб-перехватчиков Acrobat Sign, важно четко понимать правила использования информации. Обязательно задайте себе следующие вопросы:
- Какие данные являются полезными при ответе?
- Кто получит доступ к этой информации?
- Какие решения и какие отчеты будут создаваться по этим данным?
- Рекомендации по получению подписанных документов. Есть несколько важных факторов, которые нужно учесть при выборе методов получения подписанных PDF от Acrobat Sign в систему управления документами.
Вполне допустимо просто выбрать вариант Документ, подписанный соглашением при создании веб-перехватчика, но вы можете также применить API Acrobat Sign для получения данных при уведомлении о создании события (например, при переходе соглашения в состояние «Готово»).
Дополнительные сведения...
Ограничения на размер кода JSON
Рабочая нагрузка JSON не может иметь размер более 10 МБ.
Если событие создает более крупную рабочую нагрузку, веб-перехватчик все равно будет вызван, но без условных атрибутов параметров (если они присутствовали в запросе), что позволяет снизить размер полезной нагрузки.
В этой ситуации в ответ включается параметр ConditionalParametersTrimmed, чтобы уведомить клиента об удалении информации conditionalParameters.
Параметр conditionalParametersTrimmed является объектом с типом массив, который содержит сведения об отброшенных ключах.
Отбрасывание применяется в следующем порядке:
- includeSignedDocuments
- includeParticipantsInfo
- includeDocumentsInfo
- includeDetailedInfo
Первыми отбрасываются подписанные документы, затем сведения об участнике, сведения о документе, и наконец подробные сведения.
Такое может происходить, например, при создании события завершения соглашения, если в него включается не только подписанный документ в кодировке base64, но и соглашение с несколькими полями формы.
Уведомления веб-перехватчика
Веб-перехватчики Acrobat Sign передают уведомления, которые имеют отношение ко всем участникам соглашения, если существует веб-перехватчик, настроенный для конкретного пользователя, одной из его групп или его учетной записи.
События соглашений обрабатываются так, что уведомления отправляются на URL-адреса всех веб-перехватчиков, настроенных для соответствующих участников этого события. Другими словами, веб-перехватчики выполняются для событий во всех применимых соглашениях, даже за пределами той группы и той учетной записи, для которых настроен веб-перехватчик.
Уведомления доставляются только для тех событий, к которым имеет отношение конкретный участник. Например, Отправитель соглашения получает почти все уведомления для этого соглашения, а Получатели— только уведомления с момента своего присоединения к этому соглашению и только по тем событиям, которые имеют к ним отношение.
Уведомления веб-перехватчика соответствуют актуальной модели аутентификации и видимости в Acrobat Sign, то есть любой пользователь получит доступ к соглашению только с того момента, когда начнется участие этого пользователя в соглашении.
Отправитель передает соглашение на подпись трем подписывающим сторонам.
- На уровне учетной записи существует WebhookX, настроенный для учетной записи отправителя.
- Подписывающая сторона1 является членом той же учетной записи, что и отправитель, но относится к другой группе, для которой настроен веб-перехватчик WebhookY.
- Подписывающая сторона2 является членом другой учетной записи, для которой настроен веб-перехватчик уровня учетной записи WebhookZ.
- Подписывающая сторона3 является членом той же учетной записи, что и Отправитель.
Отправитель посылает соглашение: веб-перехватчик WebhookX получает события «Соглашение создано» и «Соглашение отправлено», а WebhookY — только «Соглашение отправлено».
Подписывающая сторона1 подписывает соглашение: веб-перехватчик WebhookX получает событие «Соглашение отправлено», WebhookY — событие «Участник соглашения выполнил действие» и WebhookZ — событие «Соглашение отправлено».
Подписывающая сторона2 подписывает соглашение: веб-перехватчик WebhookX получает события «Участник соглашения выполнил действие» и «Соглашение отправлено», а WebhookZ отправляет уведомление «Участник соглашения выполнил действие».
Подписывающая сторона3 подписывает соглашение: веб-перехватчик WebhookX получает события «Участник соглашения выполнил действие» и «Процесс работы с соглашением завершен», WebhookY — событие «Процесс работы с соглашением завершен» и WebhookZ — событие «Процесс работы с соглашением завершен».
Повторная попытка при отключенной службе
Если целевой URL-адрес веб-перехватчика по какой-либо причине отключен, Acrobat Sign поместит документ JSON в очередь и будет в течение 72 часов повторять попытку отправки с нарастающими интервалами.
Недоставленные события сохраняются в очереди повторных попыток, и в течение следующих 72 часов предпринимаются все возможные усилия для доставки уведомлений в том порядке, в котором они создавались.
Стратегия повторной доставки уведомлений заключается в удвоении времени между попытками, начиная с 1-минутного интервала, увеличивающегося до 12 часов, что обеспечивает 15 попыток за 72 часа.
Если веб-перехватчик не отвечает в течение 72 часов и за последние 7 дней не зарегистрировано ни одной успешной доставки, этот веб-перехватчик отключается. На этот URL-адрес более не будут отправляться уведомления, пока администратор не включит веб-перехватчик снова.
Все уведомления за период, пока веб-перехватчик находится в отключенном состоянии, будут потеряны.