Configuración de webhooks para actualizaciones en tiempo real de Sign.Plus

Los webhooks le permiten recibir actualizaciones en tiempo real sobre el estado de sus sobres en Sign.Plus. Este artículo le guiará a través del proceso de configuración y gestión de webhooks para su integración con Sign.Plus.

Paso 1: Crear un webhook

Para empezar a recibir actualizaciones en tiempo real, primero necesita crear un webhook en Sign.Plus. A continuación le explicamos cómo:

1. Elija una URL de destino en la que desee recibir las notificaciones del webhook. Debe ser un endpoint en su servidor configurado para gestionar las solicitudes POST entrantes.
2. Elija el evento o eventos que desea rastrear. Sign.Plus ofrece los siguientes eventos de webhook:
   • envelope_completed

      - Cuando se completa un sobre

   • envelope_expired

      - Cuando un sobre caduca

   • envelope_declined

      - Cuando se rechaza un sobre

   • envelope_voided

      - Cuando se anula un sobre

3. Utilice la API de Sign.Plus para crear el webhook. Deberá especificar su URL de destino y el evento o eventos que desea rastrear.

Para obtener información detallada sobre cómo crear un webhook usando la API de Sign.Plus, consulte la documentación del endpoint Crear un webhook.

Paso 2: Gestionar las notificaciones de webhook

Una vez configurado su webhook, Sign.Plus enviará solicitudes POST a la URL especificada cada vez que ocurran los eventos rastreados. Esto es lo que necesita saber sobre la gestión de estas notificaciones:

1. Método de solicitud: Todas las notificaciones de webhook se envían como solicitudes HTTP 

   POST

   .

2. Estructura de la carga útil: La carga útil del webhook es un objeto JSON que contiene dos secciones principales:
   • hook

     : Contiene metadatos sobre el propio webhook.

   • data

     : Contiene información sobre el sobre que desencadenó el evento.

3. Ejemplos de carga útil: A continuación se muestran ejemplos de cargas útiles para diferentes eventos:

   // ENVELOPE_DECLINED
{
"hook": {
"id": "6697ccb204bd194fa74c22b4",
"event": "envelope_declined",
"target": "<https://webhook.site/47acfde3-bd83-4fbc-9ff1-ea0dc030e118>"
},
"data": {
"id": "6697ccb204bd194fa74c22b4",
"uid": "4a6e29bfc5344ca6ad7cc8beda456481",
"envelope_id": "6697e681c5e364c7c23710d4",
"file_name": "test"
}
}

// ENVELOPE_COMPLETED
{
"hook": {
"id": "6697ccb204bd194fa74c22b4",
"event": "envelope_completed",
"target": "<https://webhook.site/47acfde3-bd83-4fbc-9ff1-ea0dc030e118>"
},
"data": {
"id": "6697ccb204bd194fa74c22b4",
"uid": "4a6e29bfc5344ca6ad7cc8beda456481",
"envelope_id": "6697e681c5e364c7c23710d4",
"file_name": "test"
}
}

// ENVELOPE_EXPIRED
{
"hook": {
"id": "6697ccb204bd194fa74c22b4",
"event": "envelope_expired",
"target": "<https://webhook.site/47acfde3-bd83-4fbc-9ff1-ea0dc030e118>"
},
"data": {
"id": "6697ccb204bd194fa74c22b4",
"uid": "4a6e29bfc5344ca6ad7cc8beda456481",
"envelope_id": "6697e681c5e364c7c23710d4",
"file_name": "test"
}
}

// ENVELOPE_VOIDED
{
"hook": {
"id": "6697ccb204bd194fa74c22b4",
"event": "envelope_voided",
"target": "<https://webhook.site/47acfde3-bd83-4fbc-9ff1-ea0dc030e118>"
},
"data": {
"id": "6697ccb204bd194fa74c22b4",
"uid": "4a6e29bfc5344ca6ad7cc8beda456481",
"envelope_id": "6697e681c5e364c7c23710d4",
"file_name": "test"
}
}
4. Gestión de la notificación: Cuando su servidor recibe una notificación de webhook:
   • Verifique la carga útil para asegurarse de que es una notificación de webhook válida.
   • Extraiga la información relevante de la carga útil.
   • Realice las acciones necesarias según el tipo de evento (por ejemplo, actualizar su base de datos, notificar a los usuarios, desencadenar otros procesos).

   • Envíe una respuesta 

     200 OK

      para confirmar la recepción del webhook.

Los webhooks de Sign.Plus solo se enviarán desde las siguientes direcciones IP autorizadas:
34.65.253.117
34.65.146.131

Prácticas recomendadas

1. Seguridad: Asegúrese de que el endpoint de su webhook sea seguro. Considere implementar autenticación para la URL de su webhook.
2. Idempotencia: Diseñe el gestor de su webhook para que sea idempotente. Esto significa que debe producir el mismo resultado incluso si el mismo webhook se recibe varias veces.
3. Gestión de errores: Implemente una gestión de errores robusta en la lógica de procesamiento de sus webhooks.

Siguiendo esta guía, podrá configurar y gestionar webhooks de forma eficaz, lo que permitirá que su aplicación reciba actualizaciones en tiempo real sobre el estado de los sobres en Sign.Plus.