Configurando 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 manejo de webhooks para su integración con Sign.Plus.

Paso 1: Crear un webhook

Para comenzar a recibir actualizaciones en tiempo real, primero necesita crear un webhook en Sign.Plus. Así es:

1. Decide sobre una URL de destino donde quieres recibir notificaciones de webhook. Este debería ser un punto final en su servidor que está configurado para manejar solicitudes POST entrantes.
2. Elija el(los) evento(s) que desea seguir. Sign.Plus ofrece los siguientes eventos de webhook:
   • envelope_completed - Cuando un sobre está completado
   • envelope_expiró - Cuando un sobre caducó
   • envelope_declined - Cuando un sobre es rechazado
   • sobre_voided - Cuando un sobre es anulado
3. Utilice la API de Sign.Plus para crear el webhook. Necesitará especificar su URL de destino y el evento(s) que desea seguir.

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

Paso 2: Manejar notaciones webhook

Una vez que haya configurado su webhook, Sign.Plus enviará solicitudes POST a la URL especificada cada vez que ocurra el seguimiento de eventos. Esto es lo que necesitas saber sobre el manejo de estas notificaciones:

1. Método de Solicitud: Todas las notificaciones de webhook se envían como solicitudes HTTP POST.
2. Estructura de carga útil: La carga útil del webhook es un objeto JSON que contiene dos secciones principales:
   • hook: Contiene metadatos sobre el propio webhook.
   • data: Contains information about the envelope that triggered the event.
3. Payload Ejemplos: Aquí hay ejemplos de payloads 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",
"evento": "envelope_completado",
"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. Manejar la Notificación: Cuando tu 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.
   • Realizar cualquier acción necesaria basada en el tipo de evento (por ejemplo, actualizar la base de datos, notificar a los usuarios, activar otros procesos).
   • Envía una respuesta200 OKpara confirmar la recepción del webhook.

Buenas prácticas

1. Seguridad: Asegúrese de que el endpoint de su webhook esté seguro. Considere implementar autenticación para su URL de webhook.
2. Idemnización: Diseña tu gestor de webhook para que sea idempotente. Esto significa que debería producir el mismo resultado incluso si el mismo webhook se recibe varias veces.
3. Manejo de errores: Implementar un manejo robusto de errores en la lógica de procesamiento de su gancho web.

Siguiendo esta guía, podrás configurar y manejar eficazmente los webhooks permitiendo que su solicitud reciba actualizaciones en tiempo real sobre los estados de los sobres en la Firma. lus.