Configurar webhooks

Buscar

Información general

Un webhook es una devolución de llamada 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).

Efectivamente, un webhook no es más que un servicio web que acepta solicitudes de POST HTTPS de una fuente. Por lo tanto, un webhook es un servicio REST que acepta datos o un flujo de datos.

Los webhooks son para comunicación de servicio a servicio en un Modelo Push.

Cuando se produce un evento de activación, 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:

  • 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 de el estado de actualización de los datos, la eficiencia de la comunicación y 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 o envío en bloque.

El ámbito del webhook puede incluir toda la cuenta o grupos individuales a través de la interfaz de administración. Los ámbitos de usuario y recurso también son posibles a través de la API

El tipo de datos que se insertan en la URL es configurable y puede incluir elementos como la información del acuerdo, la información del participante, el documento firmado, 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 intercepte el evento de activació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 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 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 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:

  • Ya sea en un encabezado de respuesta X-AdobeSign-ClientId. Es el mismo encabezado, que se transfiere en la solicitud y se reproduce en la respuesta.
  • En el cuerpo de la respuesta de JSON con la clave X-AdobeSign-ClientId 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 dirección URL de webhook realmente desea recibir notificaciones en esa dirección URL. Si introduce accidentalmente la dirección URL incorrecta, 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 dirección URL de 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 dirección URL de webhook no reconoce ese ID de cliente, NO DEBE responder con el código de respuesta correcta y Acrobat Sign se encargará de que la dirección URL no esté registrada como webhook.

La verificación de la llamada URL de webhook se realizará en los siguientes escenarios:

  • Registro de webhook: si esta verificación de la llamada URL de webhook falla, el webhook no se creará
  • Actualización de webhook: INACTIVO a ACTIVO: si esta verificación de la llamada URL de webhook falla, el estado de 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 de webhook que se envía a la URL de 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 de 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 un cuerpo de la respuesta de JSON con una clave como xAdobeSignClientId y un valor como el mismo ID de cliente. De lo contrario, intentaremos volver a entregar la notificación a la URL de 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

Código JavaScript de muestra para obtener el ID de cliente, validarlo y devolverlo en el encabezado de 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

{

    //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:

  1. Una cuenta de Microsoft con licencia para crear aplicaciones de funciones de Azure
  2. 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 
  3. 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:

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 dirección 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

Configurar el webhook


Á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 o todos los grupos.
  • Grupo: todos los eventos suscritos que se producen en ese grupo activan la inserción. Los webhooks con ámbito de grupo solo existen en un 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 Usuarios en varios grupos habilitados 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 basados en recursos 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 extremo de la dirección URL debe estar escuchando en el puerto 443.
  • 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.


Eventos

A continuación, se muestran los eventos que pueden desencadenar una inclusión en la URL de webhook, agrupados por el objeto.

Cada evento tiene una plantilla de la carga útil JSON que se puede entregar. (Haga clic en el nombre del evento para ver los detalles de la carga útil):

  • Enviar por lotes (anteriormente Mega Sign): los eventos de Enviar por lotes se refieren únicamente a la creación del objeto principal de Enviar por lotes. Se realiza un seguimiento de los acuerdos secundarios resultantes como eventos del acuerdo.  
    • Enviar por lotes todos los eventos: se incluyen todos los eventos de Enviar por lotes. Si se definen eventos adicionales en el futuro, se incluirán automáticamente con esta configuración.  La carga de JSON se basa en el evento individual que se activa
    • Envío en lote creado: cuando se crea un envío en lote
    • Envío en lote compartido: cuando un envío en lote se comparte
    • Enviar por lotes retirado: cuando se retira un Enviar por lotes
  • Formulario web (anteriormente Widgets): los eventos de formulario web solo pertenecen a la creación de la plantilla de formulario web. Se realiza un seguimiento de los acuerdos secundarios resultantes como eventos del acuerdo.
    • Widget de todos los eventos: se incluyen todos los eventos de formulario web. Si se definen eventos adicionales en el futuro, se incluirán automáticamente con esta configuración.  La carga de JSON se basa en el evento individual que se activa
    • Widget creado: cuando se crea un formulario web
    • Widget habilitado: cuando se activa un formulario web
    • Widget deshabilitado: cuando un formulario web está desactivado
    • Widget modificado: cuando se modifica un formulario web
    • Widget compartido: cuando se comparte un formulario web
    • Error al crear el widget: cuando un formulario web se cancela automáticamente debido a un problema de conversión


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 del Participante del 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 en la URL de 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 por lotes
    • Información de Enviar por lotes - Información detallada sobre el objeto Enviar por lotes 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 de formulario web
    • Información del participante del widget - Información sobre los participantes definidos en la plantilla de 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.

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.

Autoridad de certificación que no es de confianza

  • 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.

Faltan certificados intermedios

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.

  1. 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.

  2. Verificar el certificado de cliente localmente

    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.  

    Asegúrese de que el archivo .p12 o .pfx esté protegido con contraseña.

  3. 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:

    1. Genere una clave privada para el cliente SSL:

      openssl genrsa -out client.key 2048

    2. Utilice la clave privada del cliente para generar una solicitud de certificado:

      openssl req -new -key client.key -out client.req

    3. 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

    4. 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

    5. 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

  4. Verificar el certificado de cliente con el servidor remoto

    • Utilice Postman para cargar el archivo .pfx del cliente en Configuración > Certificados.
    • Seleccione Agregar certificado para agregar el certificado del cliente.
    Configuración de Postman

    • Configure el encabezado HTTP para x-adobesign-clientid:
    Configurar el encabezado

    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.

  5. ¿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:&quot;&quot; -out clientcert.crt -nokeys
openssl pkcs12 -info -in microsoftclientssl.pfx -passin pass:&quot;&quot; -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

  • 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: su aplicación solo tiene diez 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. 

Por ejemplo, si necesita procesar y almacenar documentos firmados. Para asegurarse de que siempre puede responder en diez segundos, siempre debe realizar su trabajo en un hilo independiente o de forma asincrónica mediante una cola.

  • 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: 

1. ¿Qué datos desea devolver en la carga útil? 

2. ¿Quién accederá a esta información? 

3. ¿Qué decisiones o 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 su 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).


Cosas a tener en cuenta

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 el  conditionalParameters  se ha eliminado la información.

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.

Logotipo de Adobe

Inicia sesión en tu cuenta

Vínculos rápidos

Ver todos los planes Administrar los planes

Avisos legales    |    Política de privacidad en línea

[Feedback V2 Badge]