Webhooks en Legalesign
Qué son los webhooks
Los webhooks son tus URLs a donde Legalesign enviará actualizaciones de estado en tiempo real. Puedes crear tus propias URLs o sistemas de automatización (como MS Power Automate) pueden generarlas para iniciar un flujo de trabajo.
Por ejemplo, en esta demo creamos una URL con Microsoft Power Automate. Añadimos esa URL como webhook en Legalesign para cuando se firmen documentos. El flujo de Power Automate se activa cuando se firma un documento y automáticamente guarda esos PDFs firmados en Sharepoint. Aprende más sobre MS Power Automate.
Nota importante - debes tener permisos de Admin del equipo para recibir eventos del equipo enviados a tu webhook.
Por qué necesitas webhooks
Los webhooks te permiten mantener un sistema basado en eventos. Los webhooks te actualizarán sobre todos los eventos dentro de tus grupos. Podrías usarlos para crear tu propio panel en vivo y/o para sincronizar con tu propia base de datos.
Como se mencionó arriba, los webhooks generados por sistemas de automatización como Power Automate te permiten iniciar procedimientos de almacenamiento, correos electrónicos, mantenimiento de registros, etc., que en combinación con la API, proveen todo lo necesario para la automatización de procesos.
También está disponible un feed de suscripción en websocket en tiempo real. Esto puede ser más adecuado cuando quieres actualizaciones en vivo del lado del cliente sin exponer un endpoint webhook. El websocket expone un conjunto más amplio de eventos que los webhooks.
Sí, los webhooks pueden parecer complicados, pero realmente valen la pena y son excelentes para tu integración. Sigue leyendo.
Tipos de webhook
- Eventos en tiempo real
- Todos los eventos cada 6 minutos (legado)
- Al ocurrir un [evento] (legado)
Para webhooks legacy ver: webhooks legacy
Los webhooks se usan comúnmente para descargar un PDF firmado. Cuando crees el webhook aplica el filtro de evento 'Final PDF created'. En tu código, la request.body entrante es JSON, parsea y extrae documentId = ['data']['uuid']. Ahora emite la consulta API para descargar el PDF - GET https://eu-api.legalesign.com/api/v1/pdf/${documentId}/.
Cómo añadir o eliminar un webhook
Añadir o eliminar un webhook usando la app web
Ve a API dashboard y haz clic en la sección Webhooks. El formulario tiene controles simples para añadir o eliminar webhooks. Opcionalmente puedes aislar eventos de webhook a ciertos equipos y/o eventos.

Tus webhooks reciben eventos de todas las cuentas donde eres admin, tanto de desarrollo como producción. Usa el filtro de grupo para crear diferentes webhooks para tus varios grupos.
Añadir o eliminar un webhook usando la REST API
Consulta la sección 'webhook' al final de la navegación izquierda en la documentación API: REST API webhooks
Añadir o eliminar un webhook usando GraphQL
¡Nuevo! En el Explorador GraphiQL de Legalesign, conectado a tu cuenta Legalesign, tienes pleno control CRUD sobre webhooks. Los webhooks pueden listarse como atributo del tipo User, y existen mutaciones para createWebhook, updateWebhook y deleteWebhook.
Qué contiene un webhook
La forma más rápida de inspeccionar tus datos es añadir un webhook, enviar/firmar/rechazar algunos documentos de prueba en la app web, y luego ver el log de webhooks en el Legalesign API Dashboard.
Si necesitas una URL webhook temporal para pruebas, revisa ngrok.
Breve guía de ngrok: una vez descargado ngrok, ejecútalo en la terminal con ./ngrok http 80 y te dará una dirección https. Introdúcela como tu webhook. Ahora abre http://127.0.0.1:4040. Eso es todo, comenzarás a ver todos los webhooks y sus datos. Empieza a enviar y firmar documentos de prueba. Nota: Ngrok puede devolver un error 5XX, por lo que verás múltiples intentos y mensajes de error ya que el sistema considerará el estado 5XX como intento fallido.
Asegúrate que tu código receptor del webhook devuelva una respuesta exitosa 2XX. Si tienes varias posibles excepciones en tu código, devuelve diferentes códigos de estado 5XX. Los registros del webhook en el dashboard API te indicarán qué excepción se lanzó.
Formato del webhook en tiempo real
El formato de datos puede ser uno de dos esquemas, ya sea un esquema 'document' o un esquema 'recipient'. Inspecciona el atributo 'object' para determinar con qué esquema tratas.
Ambos esquemas también tienen un atributo 'event'. Puedes filtrar por objeto y opcionalmente evento cuando crees el webhook.
Una tabla con todos los posibles objetos y eventos está abajo. Esta imagen ilustra un objeto document (para un evento 'created'). Los esquemas JSON completos están anexados al pie de este artículo.

Las solicitudes llegan como POST con contenido JSON. Ten en cuenta que el contenido de 'data' puede ampliarse para incluir más campos con el tiempo.
Usa atributos 'tag'. Puedes configurar hasta 3 tags al crear un documento. Usando tags puede que no necesites guardar IDs de Legalesign. También puedes usar un tag para guardar un secreto con el fin de verificar la solicitud entrante (gracias Themis por la sugerencia).
Tabla de combinaciones posibles para 'object' y 'event':
| objeto | evento |
|---|---|
| document | created |
| document | rejected |
| document | finalPdfCreated |
| recipient | completed |
| recipient | rejected |
| recipient | emailOpened |
| recipient | visiting |
| recipient | bounced |
| recipient | autoReminderEmail |
| recipient | emailNotification |
La mayoría de eventos ocurren solo una vez. Las excepciones son visiting, bounced, emailNotification y autoReminderEmail, pueden ocurrir muchas veces.
No olvides desactivar la protección CSRF para la vista que recibe estas solicitudes POST.
Aquí hay un ejemplo de un objeto 'recipient', con evento 'bounced':

Observa emailBounce y emailBounceMessage en 'data'. 'emailBounceMessage' indicará el tipo de rebote como sigue:
- Rebote duro: "Message hard bounced"
- Rebote suave: "Email soft bounced (either out of office or a timeout)"
- Retrasado: "Message delayed (check email domain exists)"
El esquema puede tener nuevos atributos añadidos en cualquier momento.
Depurar webhooks en el dashboard API
Todos los webhooks se registran y puedes examinar su contenido y el código de estado http en tu dashboard API. Para aprender más revisa el Tutorial del Dashboard
Disparo manual de un webhook
Dispara manualmente un webhook usando el formulario al final de la página de Webhooks en tu Developer Portal.
Asegúrate de usar un ID real de destinatario o documento, dependiendo del evento.
Códigos de estado
Haz clic en estos enlaces para ver la tabla de referencia para estado de documento y estado de destinatario.
Verificar un webhook
El webhook firma el paquete de datos con una clave privada. Puedes verificarlo con la clave pública - descargar clave pública.
- La ubicación de la cadena de firma está en el header X-Signed-SHA256.
- Los datos que se firman es todo el request.body (como cadena).
La 'firma' está codificada en base64. Aquí un código de verificación ejemplo en node.js:
const crypto = require('crypto');
const fs = require('fs');
const cert = fs.readFileSync('/location/of/downloadedCert.crt', 'utf8');
const c = new crypto.X509Certificate(cert);
const k = c.publicKey
let verifier = crypto.createVerify('SHA256');
let rawdata = 'sentdata' //JSON stringify data in request.body
let sha256signature = 'xxx' //value of 'X-Signed-Sha256' request header.
verifier.update(rawdata);
return verifier.verify(k, sha256signature, 'base64');
Optionally HMAC based verification is available too. For HMAC, a secret key for your webhooks is shared with you. The signed value will arrive in the header X-HMAC-SHA256.
There are lots of online resources that demonstrate how to verify an HMAC value. Sample verification in python would be:
import hmac, hashlib
sentdata = 'sentdata' # JSON stringify data in request.body
hmacvalue = 'xxx' # value of 'X-HMAC-Sha256' in request header.
v = hmac.new('your secret value'.encode(), 'sentdata'.encode(), hashlib.sha256)
isValid = v.hexdigest() == hmacvalue
Or sample Salesforce Apex code to verify a HMAC is:
String message = 'JSONstring'; //sent in request.body
String privatekey = 'privateKey'; //shared value you have been given
String hmacvalue = 'xxx'; //value of 'X-HMAC-Sha256' in request header.
Boolean verified = Crypto.verifyHMac('HmacSHA256', Blob.valueOf(message), Blob.valueOf(privatekey), EncodingUtil.convertFromHex(hmacvalue));
More webhook?
If you need more webhooks for different events, or more data in them, contact us and get your request in the development pipeline.
Schema reference
There are two possible schemas, one for object 'document' and another for object 'recipient'. Both schema have top level keys 'object' and 'event'. Inspect the 'object' attribute to determine the schema you are dealing with. Or use a webhook filter to return only document or only recipient objects.
Please note that schema may get new attributes added at any time (but will not decrease).
1. JSON Schema for 'document' object
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"version": {
"type": "string",
"default": "1.0.0"
},
"object": {
"type": "string",
"default": "document"
},
"created": {
"type": "integer",
"description": "unix timestamp"
},
"id": {
"type": "string",
"format": "uuid"
},
"event": {
"type": "string",
"pattern": "^(created|rejected|finalPdfCreated)$"
},
"data": {
"type": "object",
"properties": {
"tag1": {
"type": "string"
},
"recipients": {
"type": "array",
"items": [
{
"type": "object",
"properties": {
"uuid": {
"type": "string",
"format": "uuid"
},
"email": {
"type": "string",
"format": "email"
},
"order": {
"type": "integer"
},
"status": {
"type": "integer"
"pattern": "^(4|5|10|15|20|30|35|39|40|50|60)$"
},
"lastname": {
"type": "string"
},
"roleText": {
"type": "string",
"pattern": "^(signer|approver|witness)$"
},
"firstname": {
"type": "string"
},
"statusText": {
"type": "string",
"pattern": "^(unsent|scheduled|sent|email opened|visited|fields complete|fields complete excluding signature|witnessing required|completed|download final document|rejected|withdrawn)$"
},
"resourceUri": {
"type": "string",
"format": "uri-reference"
},
"rejectReason": {
"type": "string"
}
},
"required": [
"uuid",
"email",
"order",
"status",
"lastname",
"roleText",
"firstname",
"statusText",
"resourceUri",
"rejectReason"
]
}
]
},
"groupResourceUri": {
"type": "string",
"format": "uri-reference"
},
"statusText": {
"type": "string",
"pattern": "^(available|fields complete|completed|removed|rejected|unknown)$"
},
"name": {
"type": "string"
},
"tag": {
"type": "string"
},
"resourceUri": {
"type": "string",
"format": "uri-reference"
},
"uuid": {
"type": "string",
"format": "uuid"
},
"tag2": {
"type": "string"
},
"group": {
"type": "string"
},
"status": {
"type": "integer",
"pattern": "^(10|20|30|40|50)$"
}
},
"required": [
"tag1",
"recipients",
"groupResourceUri",
"statusText",
"name",
"tag",
"resourceUri",
"uuid",
"tag2",
"group",
"status"
]
}
},
"required": [
"version",
"object",
"data",
"created",
"id",
"event"
]
}
2. JSON schema for 'recipient' object
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"version": {
"type": "string",
"default": "1.0.0"
},
"object": {
"type": "string",
"default": "recipient"
},
"created": {
"type": "integer",
"format": "date-time"
},
"id": {
"type": "string",
"format": "uuid"
},
"event": {
"type": "string",
"pattern": "^(emailOpened|bounced|visiting|rejected|completed|autoReminderEmail|emailNotification)$"
},
"data": {
"type": "object",
"properties": {
"tag": {
"type": "string"
},
"tag1": {
"type": "string"
},
"tag2": {
"type": "string"
},
"uuid": {
"type": "string",
"format": "uuid"
},
"email": {
"type": "string",
"format": "email"
},
"group": {
"type": "string",
"format": "uuid"
},
"order": {
"type": "integer"
},
"status": {
"type": "integer",
"pattern": "^(4|5|10|15|20|30|35|39|40|50|60|70)$"
},
"document": {
"type": "string"
},
"documentName": {
"type": "string"
},
"lastname": {
"type": "string"
},
"roleText": {
"type": "string"
},
"firstname": {
"type": "string"
},
"statusText": {
"type": "string",
"pattern": "^(unsent|scheduled|sent|email opened|visited|fields complete|fields complete excluding signature|witnessing required|completed|download final document|rejected|withdrawn)$"
},
"emailBounce": {
"type": "integer"
},
"resourceUri": {
"type": "string",
"format": "uri-reference"
},
"rejectReason": {
"type": "string"
},
"groupResourceUri": {
"type": "string",
"format": "uri-reference"
},
"emailBounceMessage": {
"type": "string"
},
"documentResourceUri": {
"type": "string",
"format": "uri-reference"
}
},
"required": [
"tag",
"tag1",
"tag2",
"uuid",
"email",
"group",
"order",
"status",
"document",
"documentName",
"lastname",
"roleText",
"firstname",
"statusText",
"emailBounce",
"resourceUri",
"rejectReason",
"groupResourceUri",
"emailBounceMessage",
"documentResourceUri"
]
}
},
"required": [
"version",
"object",
"data",
"created",
"id",
"event"
]
}