Guía del usuario Cancelar

Información general de Acrobat Sign Webhook

 

Guía de Adobe Acrobat Sign

Novedades

Introducción

Administrar

Enviar, firmar y administrar acuerdos

Capacidades y flujos de trabajo de acuerdos avanzados

Integrar con otros productos

Acrobat Sign Desarrolladores

Soporte y solución de problemas

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.

Antes de configurar los webhooks, asegúrese de que la red acepta los intervalos de IP necesarios para la funcionalidad.

 

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

Requisitos previos

Usted debe permitir los intervalos de IP para los webhooks a través de la seguridad de la red para que el servicio funcione. 

El servicio URL de devolución de llamada heredado de REST versión 5 utiliza los mismos intervalos de IP que el servicio webhook.

Los administradores pueden iniciar sesión en Adobe Admin Console para añadir usuarios. Una vez que haya iniciado sesión, vaya al menú del administrador y desplácese hacia abajo hasta los webhooks.

Cómo se usa

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.

Cómo activar o desactivar

El acceso a la función Webhooks está habilitado de forma predeterminada para las cuentas de nivel empresarial.

Los administradores del 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.

Vaya a la pestaña Webhooks

Limitación de velocidad basada en accesos simultáneos

Los eventos de creación y notificación de Webhook (y devolución de llamada) están limitados en el número de notificaciones simultáneas que se envían activamente al cliente desde el sistema Acrobat Sign. Este límite se aplica a la cuenta, para incluir todos los grupos dentro de la cuenta.
Este tipo de limitación de tarifas impide que una cuenta mal diseñada consuma una cantidad desproporcionada de recursos del servidor, lo que repercute negativamente en todos los demás clientes de ese entorno de servidores.

El número de eventos simultáneos por cuenta se ha calculado para garantizar que las cuentas con webhooks de buen comportamiento reciban sus notificaciones en el menor tiempo posible y rara vez se encuentren en una situación en la que las notificaciones se retrasen debido a demasiadas solicitudes. Los umbrales actuales son:

Acción
(Evento)

Máximos
eventos
simultáneos

Descripción

Creación de webhooks

10

Se permite un máximo de 10 solicitudes de creación de webhook simultáneas por cuenta.
Las solicitudes que superen este límite generarán un código de respuesta 429 TOO_MANY_REQUESTS.
 

Notificación de webhook/devolución de llamada

30

Se permite un máximo de 30 notificaciones simultáneas de webhook y de devolución de llamada por cuenta.
Las notificaciones que superen este límite se volverán a intentar según un retroceso exponencial hasta que se entreguen.

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 al remitente del acuerdo y a cualquier webhook configurado dentro del grupo desde el que se envió el acuerdo. Los webhooks de las cuentas reciben todos los eventos.

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.

Obtén ayuda de forma más rápida y sencilla

¿Nuevo usuario?