Código JavaScript de muestra para obtener el ID de cliente, validarlo y devolverlo en el encabezado de respuesta
Última actualización el
4 ene 2024
|
También se aplica a Adobe Acrobat Sign
- Integraciones de Adobe Acrobat Sign
- Novedades
- Versiones de productos y ciclo de vida
- Acrobat Sign para Salesforce
- Instalar el paquete
- Configurar el paquete
- Guía del usuario
- Habilitar autenticación digital
- Guía del desarrollador
- Guía de personalización avanzada
- Guía de asignación y plantillas de campos
- Guía del usuario de la aplicación móvil
- Guía de automatización de flujos
- Guía de Document Builder
- Configurar documentos grandes
- Guía de actualización
- Notas de la versión
- Preguntas frecuentes
- Guía de solución de problemas
- Artículos adicionales
- Acrobat Sign para Microsoft
- Acrobat Sign para Microsoft 365
- Acrobat Sign para Outlook
- Acrobat Sign para Word/PowerPoint
- Acrobat Sign para equipos
- Acrobat Sign para Microsoft PowerApps y Power Automate
- Conector de Acrobat Sign para Microsoft Search
- Acrobat Sign para Microsoft Dynamics
- Acrobat Sign para Microsoft SharePoint
- Información general
- SharePoint local: guía de instalación
- SharePoint local: guía de asignación de plantillas
- SharePoint local: guía del usuario
- SharePoint local: notas de la versión
- SharePoint Online: guía de instalación
- SharePoint Online: guía de asignación de plantillas
- SharePoint Online: guía del usuario
- SharePoint Online: guía de asignación de formularios web
- SharePoint Online: notas de la versión
- Acrobat Sign para Microsoft 365
- Acrobat Sign para ServiceNow
- Acrobat Sign para HR ServiceNow
- Acrobat Sign para SAP SuccessFactors
- Acrobat Sign para Workday
- Acrobat Sign para NetSuite
- Acrobat Sign para SugarCRM
- Acrobat Sign para VeevaVault
- Acrobat Sign para Coupa BSM Suite
- Acrobat Sign para Zapier
- Documentación para desarrolladores de Acrobat Sign
Información general
Un webhook es una solicitud HTTPS definida por el usuario que se activa cuando se produce un evento determinado en el sitio de origen (Adobe Acrobat Sign, en este caso).
Por lo tanto, un webhook es simplemente un servicio REST que acepta datos o un flujo de datos.
Los webhooks están pensados para la comunicación de servicio a servicio en un modelo PUSH.
Cuando se activa un evento suscrito, Acrobat Sign crea un POST HTTPS con un cuerpo JSON y lo envía a la dirección URL especificada.
Los webhooks ofrecen varias ventajas sobre el método de devolución de llamada anterior, algunas de las cuales son las siguientes:
- Los administradores pueden habilitar sus propios webhooks sin tener que involucrar al soporte técnico de Acrobat Sign para que muestre la URL de devolución de llamada
- Los webhooks son mejores en términos del estado de actualización de los datos, de la eficiencia de la comunicación y de la seguridad. No se requiere votación
- Los webhooks permiten diferentes niveles de ámbito (cuenta/grupo/usuario/recurso) fácilmente.
- Los webhooks son una solución de API más moderna que permite una configuración más sencilla para las aplicaciones modernas
- Se pueden configurar varios webhooks por ámbito (cuenta/grupo/usuario/recurso), donde las devoluciones de llamada debían ser únicas.
- Los webhooks permiten la selección de los datos que se van a devolver, donde las devoluciones de llamada son una solución de “todo o nada”
- Los metadatos transportados con un webhook se pueden configurar (Básico o Detallado)
- Los webhooks son mucho más fáciles de crear, editar o deshabilitar según sea necesario, ya que la interfaz de usuario está totalmente bajo el control del administrador.
Nota:
Este documento se centra principalmente en la interfaz de usuario de webhooks en la aplicación web de Acrobat Sign (anteriormente Adobe Sign).
Los desarrolladores que buscan detalles de la API pueden encontrar más información aquí:
Utilización
Los administradores primero tendrán que tener un servicio webhook, listo para aceptar la inserción entrante desde Acrobat Sign. Hay muchas opciones en este sentido, y mientras el servicio pueda aceptar solicitudes de POST y GET, el webhook tendrá éxito.
Una vez implementado el servicio, un administrador de Acrobat Sign puede crear un nuevo webhook a partir de la interfaz de Webhook en el menú Cuenta del sitio de Acrobat Sign.
Los administradores pueden configurar el webhook para que se active para los eventos del acuerdo, formulario web (Widget) o envío en bloque (MegaSign). El recurso Plantilla de biblioteca (Documento de biblioteca) también se puede configurar mediante la API.
El ámbito del webhook puede incluir toda la cuenta o grupos individuales a través de la interfaz de administración. La API permite una mayor granularidad a través de la selección de los ámbitos USUARIO o RECURSO.
El tipo de datos que se insertan en la URL es configurable y puede incluir elementos como la información del acuerdo, del participante, del documento, etc.
Una vez configurado y guardado el webhook, Acrobat Sign insertará un nuevo objeto JSON en la dirección URL definida cada vez que se active el evento de suscripción. No se requiere ninguna manipulación continua del webhook a menos que desee cambiar los criterios del activador de eventos o la carga de JSON.
Verificación de la intención de la URL del webhook
Antes de registrar un webhook correctamente, Acrobat Sign verifica que la URL del webhook proporcionada en la solicitud de registro tenga realmente la intención de recibir notificaciones o no. Para ello, cuando Acrobat Sign recibe una nueva solicitud de registro de webhook, primero realiza una solicitud de verificación a la URL del webhook. Esta solicitud de verificación es una petición GET HTTPS enviada a la URL de webhook. Esta solicitud tiene un encabezado HTTP personalizado X-AdobeSign-ClientId. El valor de este encabezado se establece en el ID de cliente (ID de aplicación) de la aplicación de API que solicita crear o registrar el webhook. Para registrar correctamente un webhook, la URL del webhook responde a esta solicitud de verificación con un código de respuesta 2XX Y, además, PUEDE devolver el mismo valor de ID de cliente de una de las dos maneras siguientes:
- Ya sea en un encabezado de respuesta X-AdobeSign-ClientId. En el mismo encabezado que se transfiere en la solicitud y se reproduce en la respuesta.
- En el cuerpo de la respuesta JSON con la clave xAdobeSignClientId y su valor es el mismo ID de cliente que se envía en la solicitud.
El webhook se registrará correctamente solo en una respuesta correcta (código de respuesta 2XX) y validación del ID de cliente en el encabezado o el cuerpo de la respuesta. El propósito de esta solicitud de verificación es demostrar que la URL del webhook realmente desea recibir notificaciones en esa URL. Si escribe la dirección URL incorrecta por accidente, esta no responderá correctamente a la solicitud de verificación de la intención, y Acrobat Sign no enviará ninguna notificación a dicha dirección URL. Además, la URL del webhook también puede validar que recibiría notificaciones solo a través de los webhooks registrados por una aplicación específica. Esto se puede hacer validando el ID de cliente de la aplicación pasada en el encabezado X-AdobeSign-ClientId. Si la URL del webhook no reconoce ese ID de cliente, NO DEBE responder con el código de respuesta correcta, y Acrobat Sign se encarga que no se registre la URL como webhook.
La verificación de la llamada URL del webhook se realizará en los siguientes escenarios:
- Registro del webhook: si esta verificación de la llamada URL del webhook falla, el webhook no se crea.
- Actualización del webhook: INACTIVO a ACTIVO: si esta verificación de la llamada URL del webhook falla, el estado del webhook no se cambiará a ACTIVO.
Cómo responder a una notificación de webhook
Acrobat Sign realiza una verificación implícita de la intención en cada solicitud de notificación del webhook que se envía a la URL del webhook. Por lo tanto, cada solicitud HTTPS de notificación de webhook también contiene el encabezado HTTP personalizado denominado X-AdobeSign-ClientId. El valor de este encabezado es el ID de cliente (ID de aplicación) de la aplicación que creó el webhook. Consideraremos que la notificación del webhook se ha enviado correctamente si, y solo si, se devuelve una respuesta de éxito (código de respuesta 2XX) y se envía el ID de cliente en el encabezado HTTP (X-AdobeSign-ClientId) o en el cuerpo de la respuesta de JSON con una clave como xAdobeSignClientId y un valor como el mismo ID de cliente. De lo contrario, se intentará volver a entregar la notificación a la URL del webhook hasta que se agoten los reintentos.
Como se ha mencionado anteriormente, el encabezado “X-AdobeSign-ClientId” se incluye en todas las solicitudes de notificación de Sign y el valor de este encabezado (ID de cliente) se debe repetir como respuesta de dos formas:
1. Encabezado HTTP X-AdobeSign-ClientId y valor como este ID de cliente
|
|
|---|
|
// Recuperar ID de cliente var clientid = request.headers['X-ADOBESIGN-CLIENTID'];
//Validarlo if (clientid ==="BGBQIIE7H253K6") //Reemplace “BGBQIIE7H253K6” por el ID de cliente de la aplicación que utiliza para crear el webhook { //Devuélvalo en el encabezado de respuesta response.headers['X-AdobeSign-ClientId'] = clientid; response.status = 200; // valor predeterminado } |
|
Código PHP de muestra para obtener el ID de cliente, validarlo y devolverlo en el encabezado de respuesta |
|---|
|
<?php // Recuperar ID de cliente $clientid = $_SERVER['HTTP_X_ADOBESIGN_CLIENTID']; //Validarlo if($clientid == "BGBQIIE7H253K6") //Reemplace 'BGBQIIE7H253K6' por el ID de cliente de la aplicación que usa el webhook para su creación { //Devuélvalo en el encabezado de respuesta header("X-AdobeSign-ClientId:$clientid"); header("HTTP/1.1 200 OK"); // valor predeterminado } ?> |
2. Cuerpo de la respuesta de JSON con la clave xAdobeSignClientId y el valor como el mismo ID de cliente
|
Código JavaScript de muestra para obtener el ID de cliente, validarlo y devolverlo en el cuerpo de la respuesta |
|---|
|
// Recuperar ID de cliente var clientid = request.headers['X-ADOBESIGN-CLIENTID'];
//Validarlo if (clientid ==="BGBQIIE7H253K6") //Reemplace “BGBQIIE7H253K6” por el ID de cliente de la aplicación que utiliza para crear el webhook { var responseBody = { "xAdobeSignClientId" : clientid // Devuelva el ID de cliente en el cuerpo }; response.headers['Content-Type'] = 'application/json'; response.body = responseBody; response.status = 200; } |
|
Código PHP de ejemplo para obtener el ID de cliente, validarlo y devolverlo en el cuerpo de la respuesta |
|---|
|
<?php // Recuperar ID de cliente $clientid = $_SERVER['HTTP_X_ADOBESIGN_CLIENTID']; //Validarlo if($clientid == "BGBQIIE7H253K6") //Reemplace 'BGBQIIE7H253K6' por el ID de cliente de la aplicación que usa el webhook para su creación { //Devolverlo en el cuerpo de la respuesta header("Content-Type: application/json"); $body = array('xAdobeSignClientId' => $clientid); echo json_encode($body); header("HTTP/1.1 200 OK"); // valor predeterminado } ?> |
|
Cuerpo JSON de muestra de la respuesta |
|---|
|
{ "xAdobeSignClientId": "BGBQIIE7H253K6" } |
Requisitos previos
Necesitará lo siguiente:
- Una cuenta de Microsoft con licencia para crear aplicaciones de funciones de Azure
- Una aplicación de funciones de Azure existente, puede crear una usando https://docs.microsoft.com/es-es/azure/azure-functions/functions-create-first-azure-function
- Conocimiento básico de Javascript, para que pueda comprender y escribir el código en cualquier idioma de su elección
Pasos para crear un activador de funciones de Azure que funcione como webhook de Acrobat Sign
Para crear una función de activación de HTTP de Javascript:
1. Inicie sesión a través de su cuenta de Microsoft https://portal.azure.com/
2. Abra la aplicación de funciones de Azure que se muestra en la pestaña Aplicaciones de funciones.
Se abrirá la lista de aplicaciones de funciones de Azure:
3. Elija la aplicación en la que desea crear esta nueva función
4. Haga clic en el botón Crear (+) para crear una nueva función de Azure
5. Seleccione Webhook + API como escenario y Javascript como idioma
6. Haga clic en Crear esta función
Se crea una nueva función que tiene la capacidad de gestionar una solicitud de API entrante.
Añadir lógica para registrar el webhook de Acrobat Sign
Antes de registrar un webhook correctamente, Acrobat Sign verifica que la dirección URL de webhook proporcionada en la solicitud de registro tenga realmente la intención de recibir notificaciones o no. Para ello, cuando Acrobat Sign recibe una nueva solicitud de registro de webhook, primero realiza una solicitud de verificación a la dirección URL de webhook. Esta solicitud de verificación es una petición GET HTTPS enviada a la dirección URL de webhook con un encabezado HTTP personalizado X-AdobeSign-ClientId. El valor de este encabezado se establece en el ID de cliente de la aplicación que solicita crear o registrar el webhook. Para registrar correctamente un webhook, la URL de webhook responde a esta solicitud de verificación con un código de respuesta 2XX Y, además, puede devolver el mismo valor de ID de cliente de una de las dos maneras siguientes.
Hay dos opciones que puede seguir:
Opción 1: Transfiera el ID de cliente a X-AdobeSign-ClientId como encabezado de respuesta
Transfiera X-AdobeSign-ClientId en el encabezado de la respuesta. Es el mismo encabezado, que se transfiere en la solicitud y debe reproducirse en la respuesta.
Reemplace el archivo Index.js con lo siguiente:
module.exports = function (context, req) {
var clientId = req.headers['x-adobesign-clientid'];
// Validar que el ClientID entrante sea genuino
if (clientId === '123XXX456') {
context.res = {
// status: 200, /* El valor predeterminado es 200 */ // Cualquier respuesta 2XX es aceptable
body: "Notificación aceptada",
headers : {
'x-adobesign-clientid' : req.headers['x-adobesign-clientid']
}
};
}
else {
context.res = {
status: 400,
body: "¡Vaya! Llamada ilegítima identificada"
};
}
context.done();
};
Pruebe el comportamiento simulando la solicitud:
1. Haga clic en el botón de Prueba en la esquina derecha
2. Simular la solicitud ficticia
Aunque los encabezados de respuesta no se muestran arriba, pero se puede observar a través de la simulación por postman/DHC o cualquier otro servicio.
Opción 2: Transfiera el ID de cliente en el cuerpo de la respuesta con la clave xAdobeSignClientId
En el cuerpo de la respuesta de JSON con la clave de xAdobeSignClientId y su valor es el mismo ID de cliente que se envía en la solicitud.
Reemplace el archivo Index.js con lo siguiente:
module.exports = function (context, req) {
var clientId = req.headers['x-adobesign-clientid'];
// Validar que el ClientID entrante sea genuino
if (clientId === '123XXX456') {
context.res = {
// status: 200, /* El valor predeterminado es 200 */ // Cualquier respuesta 2XX es aceptable
body: {
'xAdobeSignClientId' : clientId
},
headers : {
'Tipo de contenido' : 'application/json'
}
};
}
else {
context.res = {
status: 400,
body: "¡Vaya! Llamada ilegítima identificada"
};
}
context.done();
};
Pruebe el comportamiento simulando la solicitud
1. Haga clic en el botón de Prueba en la esquina derecha
2. Simular la solicitud ficticia
Tenga en cuenta también que se espera el mismo comportamiento para clientID cuando la URL de webhook recibe notificaciones del POST.
Listo para usar
Una vez que haya verificado el comportamiento, la URL del webhook funciona según los estándares de Acrobat Sign. Puede actualizar aún más la lógica personalizada según sus requisitos.
Obtener la URL de función
- Haga clic en Obtener la URL de función
Copie la URL y utilícela para crear webhooks en Acrobat Sign.
Creación de la función AWS Lambda
Para crear una función AWS Lambda, inicie sesión en su AWS Management Console y seleccione el servicio AWS Lambda en la lista de servicios.
- Haga clic en Crear una función lambda usando la opción Autor desde cero
- En la página Configurar función introduzca el nombre de función lambdaWebhooks y seleccione Node.js 4.3 como motor de ejecución
- Para la Función elija una función existente o cree una nueva función a partir de plantillas
- Si ha elegido Crear nuevo rol a partir de plantillas introduzca un nombre de función (p. ej. role-lambda) y seleccione Permisos simples de Microservicios de la lista de Plantillas de políticas
- Haga clic en el botón Crear función
- En la nueva página de la función lambda de AWS, seleccione Editar código en línea como Tipo de entrada de código, mantenga index.handler como Controlador.
- Añadir lógica para registrar el webhook de Acrobat Sign
Antes de registrar un webhook correctamente, Acrobat Sign verifica que la dirección URL de webhook proporcionada en la solicitud de registro tenga realmente la intención de recibir notificaciones o no. Para ello, cuando Acrobat Sign recibe una nueva solicitud de registro de webhook, primero realiza una solicitud de verificación a la dirección URL de webhook. Esta solicitud de verificación es una petición GET HTTPS enviada a la dirección URL de webhook con un encabezado HTTP personalizado X-AdobeSign-ClientId. El valor de este encabezado se establece en el ID de cliente de la aplicación que solicita crear o registrar el webhook. Para registrar correctamente un webhook, la URL de webhook responde a esta solicitud de verificación con un código de respuesta 2XX Y, además, puede devolver el mismo valor de ID de cliente de una de las dos maneras siguientes. Tenga en cuenta también que se espera el mismo comportamiento para clientID cuando la URL de webhook recibe notificaciones del POST.
Siga uno de los dos casos:
Caso 1: Transfiera el ID de cliente a X-AdobeSign-ClientId como encabezado de respuesta
- Transfiera X-AdobeSign-ClientId en el encabezado de la respuesta. Es el mismo encabezado, que se transfiere en la solicitud y debe reproducirse en la respuesta.
Fragmento de código
En el archivo index.js, reemplace el fragmento de código generado automáticamente por el código siguiente:
- Transfiera X-AdobeSign-ClientId en el encabezado de la respuesta. Es el mismo encabezado, que se transfiere en la solicitud y debe reproducirse en la respuesta.
|
El código JS de nodo de ejemplo para obtener el ID de cliente, validarlo y, a continuación, devolverlo en el encabezado de respuesta |
|---|
|
exports.handler = function index(event, context, callback) { // Recuperar ID de cliente var clientid = event.headers['X-AdobeSign-ClientId'];
//Validarlo if (clientid =="BGBQIIE7H253K6") //Reemplace 'BGBQIIE7H253K6' por el ID de cliente de la aplicación que utiliza para crear el webhook { var response = { statusCode: 200, headers: { "X-AdobeSign-ClientId": clientid } }; callback(null,response); } else { callback("¡Vaya! llamada ilegítima"); } } |
Caso 2: Transferir el ID de cliente en el cuerpo de la respuesta con la clave xAdobeSignClientId
En el cuerpo de la respuesta de JSON con la clave de xAdobeSignClientId y su valor es el mismo ID de cliente que se envía en la solicitud.
Fragmento de código
Reemplace el archivo Index.js con lo siguiente:
|
El código JS de nodo de ejemplo para obtener el ID de cliente, validarlo y, a continuación, devolverlo en el encabezado de respuesta |
|---|
|
exports.handler = function index(event, context, callback) { // Recuperar ID de cliente var clientid = event.headers['X-AdobeSign-ClientId'];
//Validarlo if (clientid =="BGBQIIE7H253K6") //Reemplace 'BGBQIIE7H253K6' por el ID de cliente de la aplicación que utiliza para crear el webhook { var responseBody = { xAdobeSignClientId : clientid };
var response = { statusCode: 200, body: JSON.stringify(responseBody) };
callback(null,response); } else { callback("¡Vaya! llamada ilegítima"); } } |
- Guarde la función. Se crea la función lambda y estamos casi listos para usarla en un webhook en tiempo real.
Configuración de AWS API Gateway
Para que esta lambda sea accesible públicamente a través de un método HTTP, necesitamos configurar AWS API Gateway usando nuestra función (creada anteriormente) como back-end para la API.
En AWS Management Console, seleccione la API Gateway en los servicios de AWS y haga clic en el botón Crear API
- En la página Crear nueva API seleccione Nueva API e introduzca webhooks como el Nombre de API.
- Haga clic en el botón Crear API
- Seleccione la lista desplegable Acciones y seleccione la opción Crear recurso
- Compruebe la opción Configurar como recurso proxy y escriba validar como el Nombre del recurso y {proxy+} en la Ruta de recurso
- Deje la opción Activar API Gateway CORS y haga clic en el botón Crear recurso
- Guarde el Proxy de función lambda seleccionado como Tipo de integración y seleccione el área geográfica donde ha creado su función lambda en la lista desplegable Región de lambda (probablemente sea la misma región donde está creando la puerta de enlace de API).
- Entre validar como la Función lambda y haga clic en el botón Guardar
- En la ventana emergente Agregar permiso a la función lambda seleccione OK
Si todos los pasos anteriores se ejecutan correctamente, verá algo como esto:
Implementación de API
El siguiente paso es implementar esta API para que esté lista para usarse.
- En el desplegable Acciones seleccione Implementar API
- Seleccionar [Nueva fase] en la Fase de implementación e introduzca prod (o algo que desee para identificar esta etapa) en el Nombre de fase
- Haga clic en el botón Implementar.
La API ya está lista para usarse y puede encontrar la URL de invocación en el cuadro azul, como se muestra a continuación:
Tome nota de esta URL, ya que tendrá que introducirla como su URL de webhook en tiempo real.
Listo para usar
Ya está hecho. Utilice esta URL anterior con "/{nodeJSfunctionName}"POST /webhooks. Una vez que haya verificado el comportamiento, la URL del webhook funciona según los
estándares de Acrobat Sign. Puede actualizar o añadir la lógica personalizada según sus necesidades.
Opciones de configuración
La configuración del webhook requiere que se definan cinco elementos:
- Nombre: se sugiere el uso de un nombre intuitivo que otros administradores puedan comprender fácilmente.
- Ámbito: ¿qué anchura de red cubre el webhook? La cuenta y el grupo están disponibles en la interfaz.
- La API es compatible con los ámbitos de Cuenta, Grupo, Usuario y Recursos.
- Únicamente se puede definir un Ámbito por webhook.
- URL: la dirección URL de destino en la que Acrobat Sign ha insertado la carga de JSON.
- Eventos: el activador que hace que Acrobat Sign cree el JSON y lo inserte en la URL.
- Cada evento crea una carga diferente relevante para el evento de activación.
- Varios Eventos se pueden incluir en un webhook.
- Parámetros de notificación: los Parámetros de notificación identifican la carga del Evento JSON, lo que le permite seleccionar solo las secciones del Evento que son importantes para este webhook (y, por lo tanto, reducen los datos innecesarios en la URL).
Cuando el webhook esté completamente definido, haga clic en Guardar y el nuevo webhook empezará a reaccionar para activar los eventos inmediatamente.
Nota:
Configure su URL de webhook para responder a las solicitudes de verificación y notificación de webhook según el protocolo de verificación explicado anteriormente. El ID de cliente (ID de aplicación) que se enviará a webhooks creados desde la aplicación web de Acrobat Sign será - UB7E5BXCXY
Ámbitos
- Cuenta: todos los eventos de suscripción que se producen en la cuenta activan la inserción.
- Los administradores de cuentas tienen autoridad para ver todos los webhooks definidos para la cuenta y todos los grupos de esa cuenta.
- Grupo: todos los eventos suscritos que se producen en ese grupo activan la inserción. NOTA: los webhooks de ámbito de grupo solo existen para ese grupo.
- Los administradores de grupo solo verán los webhooks dedicados a su grupo. No pueden ver los webhooks o webhooks de nivel de cuenta enlazados a otros grupos.
- Las cuentas que tengan habilitadas los Usuarios en varios grupos verán la opción para establecer el grupo al que se debe aplicar el ámbito.
- Cuenta de usuario: todos los eventos de suscripción de una cuenta de usuario activan la inserción. Los webhooks de nivel de usuario solo se pueden crear mediante API.
- Webhook de nivel de recurso: se creará para un recurso específico. Los eventos específicos de este recurso se insertarán en la URL del webhook. Los webhooks de nivel de recurso solo se pueden crear mediante API.
URL
Una URL de webhook es un servidor que escucha los mensajes de notificación de POST HTTPS entrantes que se activan cuando se producen eventos.
Necesita esta dirección URL para suscribirse a su webhook para eventos.
- El cliente debe incluir una dirección URL HTTPS a la que Acrobat Sign pueda ser POST. Esta URL debe estar disponible en la red pública.
- Por ejemplo, los URI 127.0.0.1 y localhost no funcionarán.
- El URL de punto final debe estar escuchando en el puerto 443 u 8443 (lo decide el cliente al definir la URL de devolución de llamada).
- Asegúrese de que el webhook admite solicitudes de POST para notificaciones de eventos entrantes y solicitudes de GET para la solicitud de verificación.
- Un cortafuegos no debe bloquear la URL.
A continuación se muestran los eventos que pueden desencadenar una inclusión en la URL del webhook, agrupados por objeto y enumerados en el orden encontrado en la IU.
El valor de la izquierda es el valor que verá en la IU de Acrobat Sign. El valor de la derecha es el nombre del webhook en la API.
Para obtener información detallada sobre los webhooks y sus cargas, consulte la Guía para desarrolladores de Acrobat Sign.
Acuerdos:
| Elemento IU | Nombre de la webhook |
| Acuerdo de todos los eventos | AGREEMENT_ALL |
| Acuerdo creado | AGREEMENT_CREATED |
| Acuerdo enviado | AGREEMENT_ACTION_REQUESTED |
| Participante en el acuerdo completado | AGREEMENT_ACTION_COMPLETED |
| Flujo de trabajo del acuerdo completado | AGREEMENT_WORKFLOW_COMPLETED |
| Acuerdo caducado | AGREEMENT_EXPIRED |
| Acuerdo eliminado | AGREEMENT_DOCUMENTS_DELETED |
| Acuerdo cancelado | AGREEMENT_RECALLED |
| Acuerdo rechazado | AGREEMENT_REJECTED |
| Acuerdo compartido | AGREEMENT_SHARED |
| Acuerdo delegado | AGREEMENT_ACTION_DELEGATED |
| Participante en el acuerdo sustituido | AGREEMENT_ACTION_REPLACED_SIGNER |
| Acuerdo modificado | AGREEMENT_MODIFIED |
| Modificación del acuerdo confirmado | AGREEMENT_USER_ACK_AGREEMENT_MODIFIED |
| Acuerdo del correo electrónico visto | AGREEMENT_EMAIL_VIEWED |
| Acuerdo del correo electrónico devuelto | AGREEMENT_EMAIL_BOUNCED |
| Error al crear el acuerdo | AGREEMENT_AUTO_CANCELLED_CONVERSION_PROBLEM |
| Evento de publicación de acuerdo sincronizado sin conexión | AGREEMENT_OFFLINE_SYNC |
| Acuerdo cargado por el remitente | AGREEMENT_UPLOADED_BY_SENDER |
| Acuerdo protegido | AGREEMENT_VAULTED |
| Identidad social del participante en el acuerdo autenticado | AGREEMENT_WEB_IDENTITY_AUTHENTICATED |
| Participante en el acuerdo autenticado mediante autenticación KBA | AGREEMENT_KBA_AUTHENTICATED |
| Se ha enviado un recordatorio del acuerdo | AGREEMENT_REMINDER_SENT |
| El firmante ha modificado el nombre del firmante del acuerdo | AGREEMENT_SIGNER_NAME_CHANGED_BY_SIGNER |
| Los webhooks del acuerdo solo están disponibles mediante una API | |
| N/A | AGREEMENT_EXPIRATION_UPDATED |
| N/A |
AGREEMENT_READY_TO_NOTARIZE |
| N/A |
AGREEMENT_READY_TO_VAULT |
Enviar en bloque:
| Elemento IU | Nombre de la webhook |
| Enviar en lote de todos los eventos | MEGASIGN_ALL |
| Enviar en lote creado |
MEGASIGN_CREATED |
| Enviar en lote compartido |
MEGASIGN_SHARED |
| Enviar en lote reclamado |
MEGASIGN_RECALLED |
Formularios web:
| Elemento IU | Nombre de la webhook |
| Todos los eventos del formulario web | WIDGET_ALL |
| Formulario web creado |
WIDGET_CREATED |
| Formulario web habilitado |
WIDGET_ENABLED |
| Formulario web deshabilitado |
WIDGET_DISABLED |
| Formulario web modificado |
WIDGET_MODIFIED |
| Formulario web compartido |
WIDGET_SHARED |
| Error al crear el formulario web |
WIDGET_AUTO_CANCELLED_CONVERSION_PROBLEM |
Plantillas de biblioteca (solo API):
| Elemento IU | Nombre de la webhook |
| N/A | LIBRARY_DOCUMENT_ALL |
| N/A | LIBRARY_DOCUMENT_CREATED |
| N/A | LIBRARY_DOCUMENT_AUTO_CANCELLED_CONVERSION_PROBLEM |
| N/A | LIBRARY_DOCUMENT_MODIFIED |
Parámetros de notificación
Los parámetros de notificación permiten personalizar la carga de JSON a elementos específicos del evento.
Por ejemplo, en un evento Participante en el acuerdo sustituido, puede que solo desee la Información del acuerdo y la Información del participante, dejando fuera la Información del documento, y reduciendo el volumen total del JSON enviado en la URL del webhook.
- Acuerdo
- Información del acuerdo: información detallada del acuerdo basada en el estado del acuerdo en el momento del evento desencadenante.
- Información del documento del acuerdo: incluye cualquier información de documento generada como resultado del evento.
- Información del participante del acuerdo: incluye la información de los participantes como resultado del evento.
- Documento firmado del acuerdo: proporciona el PDF firmado.
- Aplicable al Flujo de trabajo del acuerdo completado y a todos los eventos del Acuerdo.
- Enviar en bloque
- Información de Enviar en bloque: información detallada acerca el objeto Enviar en bloque que desencadenó el evento.
- Formulario web
- Información del widget: información detallada sobre el formulario web que activó el evento.
- Información del documento del widget: la información del documento asociada a la plantilla del formulario web.
- Información del participante del widget: información sobre los participantes definidos en la plantilla del formulario web.
Autenticación SSL bidireccional
SSL bidireccional, a menudo llamado SSL del lado del cliente o TLS mutuo, es un modo de SSL en el que tanto el servidor como el cliente (explorador web) presentan certificados para identificarse.
Los administradores de cuentas pueden configurar un certificado del lado del cliente en la página de Configuración de seguridad.
Acrobat Sign verifica los certificados SSL al entregar cargas a la URL de webhook. Los webhooks que no superen la verificación del certificado SSL no entregarán correctamente la carga útil de JSON.
Utilice SSL bidireccional para autenticar el cliente (Acrobat Sign) y el servicio de escucha para garantizar que solo Acrobat Sign pueda alcanzar la URL de webhook.
Si el webhook fue creado por una Aplicación para socios, el webhook utilizará un certificado de cliente (si está disponible) de la cuenta de la aplicación asociada para identificarse a sí mismo al realizar devoluciones de llamada webhook.
A continuación, se muestran las preguntas más comunes relativas al proceso de verificación del servidor web y a la verificación de la certificación del cliente.
Verificación del servidor web
Durante el registro de un webhook, Acrobat Sign verifica la URL del servidor webhook.
Los clientes no podrán registrar el webhook si la conexión con la URL de devolución de llamada webhook no se puede completar desde Acrobat Sign.
No.
La URL de devolución de llamada webhook solo puede ser HTTPS en el puerto 443 u 8443.
Acrobat Sign bloquea el tráfico HTTPS saliente para todos los demás puertos.
Una buena forma de comprobar el certificado de servidor es utilizar la herramienta DigiCert® SSL Installation Diagnostics Tool.
Introduzca solo el nombre de host, por ejemplo, www.digicert.com
Estos son algunos problemas comunes:
- Problema: utilizar una autoridad de certificación que no es de confianza o un certificado autofirmado
Solución: utilice un certificado SSL emitido por una autoridad de certificación pública para el servidor de devolución de llamada webhook.
- Problema: el servidor no envía el certificado intermedio
Solución: instale los certificados intermedios en el servidor de devolución de llamada webhook.
Consulte https://www.digicert.com/kb/ssl-certificate-installation.htm para obtener información detallada.
Verificación de certificados de cliente
Para configurar un SSL bidireccional de webhook, se requiere que el administrador cargue un archivo .p12 (o .pfx) que contenga la clave privada. El archivo se almacena de forma segura en la cuenta del cliente y el administrador tiene control total para eliminarlo en cualquier momento.
En una configuración de webhook bidireccional, Acrobat Sign es quien llama/el cliente y necesita la clave privada para demostrar que Acrobat Sign realiza la llamada en nombre de la cuenta del cliente.
-
Compruebe que SSL bidireccional está activado
SSL bidireccional debe estar habilitado en el servidor de devolución de llamada webhook.
Con cualquier navegador web, conéctese a la URL de devolución de llamada webhook. Debería obtener:
400 Solicitud incorrecta No se ha enviado el certificado SSL obligatorio
Esto significa que el servidor espera que el cliente envíe certificados de cliente (es decir, SSL bidireccional está habilitado para el servidor).
Si no ve el mensaje anterior, SSL bidireccional no está habilitado.
Nota:Puede utilizar Postman y realizar una solicitud POST a la URL de devolución de llamada webhook. Debería obtener un resultado similar.
-
Las credenciales del cliente pueden ser un certificado autofirmado o uno emitido por una autoridad de certificación. Sin embargo, debe cumplir como mínimo con las siguientes extensiones X.509 v3:
Extensión X.509 v3
Valor
ExtendedKeyUsage
clientAuth (OID: 1.3.6.1.5.5.7.3.2)
KeyUsage
digitalSignature
El certificado de cliente debe ser un archivo PKCS12 con extensión .p12 o .pfx, y debe incluir tanto el certificado de cliente (para que el servidor pueda verificar su identidad) como la clave privada del cliente (para que el cliente pueda firmar digitalmente los mensajes, de modo que el servidor los verifique durante el protocolo de enlace SSL).
Utilice el comando openssl para verificar el archivo p12 (pfx):
openssl pkcs12 -info -in outfile.p12
Debe solicitarse la contraseña de la clave privada. La salida debe contener ambos certificados y una clave privada cifrada, como:
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-----Los certificados deben incluir como mínimo el certificado de entidad final y los certificados intermedios. Lo ideal sería incluir también el certificado raíz de la autoridad de certificación.
Alerta:Asegúrese de que el archivo .p12 o .pfx esté protegido con contraseña.
-
Crear un certificado de cliente autofirmado (opcional)
Los certificados de cliente pueden emitirlos autoridades de certificación o ser autofirmados, según sus necesidades.
Para generar un certificado de cliente autofirmado, utilice el siguiente comando openssl:
openssl req -newkey rsa:4096 -keyform PEM -keyout ca.key -x509 -days 3650 -outform PEM -out ca.cer
Precaución:Mantenga en secreto los archivos resultantes, ya que son sus certificados de autoridad de certificación autofirmados.
A continuación, genere el archivo .p12 del cliente:
- Genere una clave privada para el cliente SSL:
openssl genrsa -out client.key 2048
- Utilice la clave privada del cliente para generar una solicitud de certificado:
openssl req -new -key client.key -out client.req
- Emita el certificado de cliente utilizando la solicitud de certificado y la clave/certificado de la autoridad de certificación:
openssl x509 -req -in client.req -CA ca.cer -CAkey ca.key -set_serial 101 -extensions client -days 365 -outform PEM -out client.cer
- Convierta el certificado de cliente y la clave privada al formato pkcs#12 para su uso en navegadores:
openssl pkcs12 -export -inkey client.key -in client.cer -out client.p12
- Quite la clave privada del cliente, el certificado del cliente y los archivos de solicitud del cliente, ya que pkcs12 tiene todo lo que necesita.
rm client.key client.cer client.req
- Genere una clave privada para el cliente SSL:
-
- Utilice Postman para cargar el archivo .pfx del cliente en Configuración > Certificados.
- Seleccione Agregar certificado para agregar el certificado del cliente.
- Configure el encabezado HTTP para x-adobesign-clientid:
Una vez realizada la configuración, envíe una petición POST a la URL de devolución de llamada webhook.
Debería obtener la respuesta 200.
-
¿Por qué Acrobat Sign rechaza mi archivo .pfx incluso después de haberlo verificado con Postman?
Si ha seguido el proceso anterior para la verificación del archivo pfx y Acrobat Sign sigue rechazándolo, es probable que el archivo se haya generado mediante una herramienta de Microsoft capaz de producir archivos PKCS12 no estándar.
En ese caso, utilice los siguientes comandos openssl para extraer los certificados y la clave privada del archivo .pfx y, a continuación, genere un archivo PKCS12 con el formato correcto:
// Extraer certificados y clave privada del archivo .pfx 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 // Crear nuevo archivo PKCS12 openssl pkcs12 -export -inkey clientcert.key -in clientcert.crt -out clientcert.pfx
Cómo activar o desactivar
El acceso a la función Webhooks está habilitado de forma predeterminada para las cuentas del plan Enterprise.
Los administradores de nivel de grupo pueden crear o controlar los webhooks que solo funcionan dentro de su grupo.
El acceso a la página Webhooks se encuentra en el carril izquierdo del menú Administración: Cuenta > Webhooks
Activación de un webhook
Cuando se crea un webhook por primera vez, se crea en estado Activo.
En la página Webhooks de Acrobat Sign, verá los webhooks activos de forma predeterminada.
Para activar un webhook inactivo:
- Haga clic en el icono de Opciones (tres líneas horizontales) a la derecha de la fila de encabezado de webhooks y seleccione Mostrar todos los webhooks
- Haga clic una vez en el acuerdo inactivo para seleccionarlo
- Esto muestra las opciones del webhook justo debajo de la fila de encabezado
- Haga clic en Activar
El webhook activo comenzará a enviar datos a la dirección URL de destino tan pronto como se active el siguiente evento.
Desactivación de un webhook
La desactivación de un webhook solo requiere que usted
- Vaya a la página Webhooks
- Haga un solo clic en el usuario que desee editar.
- Seleccionar Desactivar en los elementos de menú bajo la fila de encabezado
- Una vez desactivado, el webhook muestra un estado de Inactivo
Ver o editar un webhook
Los webhooks se pueden editar y guardar en cualquier momento y, al guardar una nueva configuración, ese cambio surte efecto inmediatamente.
Solo los Eventos y Parámetros de notificación se puede editar.
Si el Nombre, Ámbito o URL se tiene que cambiar, tendrá que crearse un nuevo webhook.
Para editar los parámetros de un webhook:
- Vaya a la página Webhooks
- Haga un solo clic en el webhook que desee editar
- Haga clic en la opción Ver/Editar bajo la fila de encabezado
- Aplique los cambios necesarios y haga clic en Guardar
Eliminar un webhook
Un webhook se puede eliminar en cualquier momento.
Al eliminar un webhook, se destruye en el sistema, por lo que no se puede recuperar un webhook eliminado.
No es necesario desactivar primero los webhooks.
Para eliminar un webhook:
- Vaya a Webhooks
- Seleccione el webhook que desea eliminar haciendo clic en él
- Haga clic en la opción Eliminar bajo la fila de encabezado
- Se presenta un desafío para asegurarse de que desea eliminar el webhook. haga clic en OK.
Prácticas recomendadas
- Suscribirse a eventos específicos necesarios para limitar el número de solicitudes HTTPS al servidor: cuanto más específica pueda hacer sus webhooks, menos volumen tendrá que seleccionar.
- Ser resistente a duplicados: si tiene más de una aplicación que comparte la misma URL de webhook y el mismo usuario asignado a cada aplicación, se enviará el mismo evento a su webhook varias veces (una vez por aplicación). En algunos casos, su webhook puede recibir eventos duplicados. La aplicación webhook debe tolerar esto y deduplicarse por ID de evento.
- Responda siempre a los webhooks rápidamente: la aplicación solo tiene cinco segundos para responder a las solicitudes de webhook. En el caso de la solicitud de verificación, esto no suele ser un problema, ya que la aplicación no necesita realizar ningún trabajo real para responder. Sin embargo, para las solicitudes de notificación, la aplicación suele hacer algo que lleva tiempo en respuesta a la solicitud. Se recomienda trabajar en un hilo independiente o utilizar una cola de forma asincrónica para garantizar que pueda responder en cinco segundos.
- Administrar simultaneidad: cuando un usuario realiza una serie de cambios en sucesión rápida, es probable que su aplicación reciba varias notificaciones para el mismo usuario aproximadamente al mismo tiempo. Si no tiene cuidado con la administración de la concurrencia, la aplicación puede terminar procesando los mismos cambios para el mismo usuario más de una vez. Para poder utilizar los webhooks de Acrobat Sign, es necesario entender claramente el uso de la información. Asegúrese de hacer preguntas como:
- ¿Qué datos desea devolver en la carga útil?
- ¿Quién accederá a esta información?
- ¿Qué decisiones o creación de informes se generarán?
- Recomendaciones para la recepción de documentos firmados: existen varios factores que se deben tener en cuenta a la hora de determinar cómo recibir un PDF firmado de Acrobat Sign en el sistema de gestión de documentos.
Si bien es perfectamente aceptable seleccionar el Documento firmado del acuerdo al crear un webhook, puede que le interese utilizar la API de Acrobat Sign para recuperar los documentos cuando se reciba un evento de activación (como el estado Completado del acuerdo).
Cuestiones importantes
Limitación de tamaño de JSON
El tamaño de la carga útil de JSON está limitado a 10 MB.
Si un evento genera una carga más grande, se activará un webhook, pero se eliminarán los atributos de parámetro condicional, si están en la solicitud, para reducir el tamaño de la carga.
"ConditionalParametersTrimmed " se devolverá en la respuesta cuando esto ocurra para informar al cliente de que la información conditionalParameters se ha eliminado.
conditionalParametersTrimmed es un objeto de matriz que contiene la información sobre las claves que se han recortado.
El truncamiento se realizará en el orden siguiente:
- includeSignedDocuments
- includeParticipantsInfo
- includeDocumentsInfo
- includeDetailedInfo
Los documentos firmados se truncarán primero, seguidos de la información del participante, la información del documento y, por último, la información detallada.
Esto puede ocurrir, por ejemplo, en un evento de finalización de acuerdo si incluye también un documento firmado (codificado en base 64) o en un acuerdo con varios campos de formulario
Notificaciones de webhook
Los webhooks de Acrobat Sign envían notificaciones que son aplicables a todos los participantes de un acuerdo si hay un webhook configurado para ese usuario, su grupo o su cuenta.
Los eventos del acuerdo se procesan de forma que, si hay un webhook configurado para el participante aplicable de ese evento, se envíe una notificación a esa dirección URL de webhook. En otras palabras, los webhooks se activan para eventos en todos los acuerdos aplicables, incluso los que están fuera del grupo o cuenta en los que está configurado el webhook.
Las notificaciones se entregan solo para los eventos en los que participa el participante. Por ejemplo, el Remitente de un acuerdo recibe casi todas las notificaciones, mientras que los Destinatarios solo recibirán notificaciones desde el inicio de su participación en el acuerdo, y solo para aquellos eventos en los que estén involucrados.
Las notificaciones de webhook siguen el modelo actual de autenticación y visibilidad del propio Acrobat Sign, lo que significa que los usuarios solo tendrán acceso al acuerdo cuando se haya iniciado la participación del usuario en un acuerdo.
El Remitente envía un acuerdo para su firma a tres firmantes.
- Hay un nivel de cuenta WebhookX configurado para la cuenta Remitentes.
- Firmante1 es miembro de la misma cuenta que el remitente, pero en un grupo diferente, y hay un WehbhookY configurado para ese grupo.
- Firmante2 es miembro de una cuenta diferente y hay un nivel de cuenta WebhookZ configurado para la cuenta del Firmante2.
- Firmante3 es miembro de la misma cuenta que un remitente.
El Remitente envía un acuerdo: WebhookX se activa en Acuerdo creado y Acuerdo enviado mientras WebhookY se activa en Acuerdo enviado.
Firmante1 firma: WebhookX se activa en Participante del acuerdo completado y Acuerdo enviado, WebhookY se activa en Participante del acuerdo completado y WebhookZ se activa en Acuerdo enviado.
Firmante2 firma: WebhookX se activa en Participante del acuerdo completado y Acuerdo enviado mientras que WebhookZ envía una notificación para Participante del acuerdo completado.
Firmante3 firma: WebhookX se activa en Participante del acuerdo completado y Flujo de trabajo del acuerdo completado, WebhookY se activa en Flujo de trabajo del acuerdo completado, y WebhookZ se activa en Flujo de trabajo del acuerdo completado.
Reintentar cuando el servicio de escucha esté inactivo
Si la dirección URL de destino de webhook está desactivada por cualquier motivo, Acrobat Sign pone el JSON en cola y vuelve a intentar la inclusión en un ciclo progresivo durante 72 horas.
Los eventos no entregados se conservan en una cola de reintentos y durante las siguientes 72 horas se intenta enviar las notificaciones en el orden en que se produjeron.
La estrategia para reintentar la entrega de notificaciones consiste en duplicar el tiempo entre intentos, comenzando con un intervalo de 1 minuto que aumenta a cada 12 horas, lo que se traduce en 15 reintentos en un lapso de 72 horas.
Si el receptor webhook no responde en un plazo de 72 horas y no se han realizado entregas de notificación correctas en los últimos siete días, el webhook se desactivará. No se enviarán notificaciones a esta dirección URL hasta que se active de nuevo el webhook.
Se perderán todas las notificaciones entre el momento en que se desactive el webhook y se active de nuevo posteriormente.
