Enviar eventos de documentos a tu sistema con webhooks

Un webhook envía un JSON firmado a tu URL cuando un documento se envía, se abre, se firma, se completa, se rechaza, caduca o se cancela. Requiere Pro; lo configuran propietarios y administradores.

Un webhook envía un mensaje a una URL tuya cada vez que pasa algo con un documento, para que tu propio sistema pueda reaccionar. Los webhooks forman parte de Pro: funcionan en un espacio de trabajo mientras uno de sus propietarios tenga Pro, y solo los propietarios y administradores pueden gestionarlos. Cada espacio de trabajo tiene los suyos.

Añadir un webhook

  1. Abre Ajustes y marca en el menú de la cuenta y ve a Integraciones.
  2. Pulsa Añadir webhook.
  3. Introduce la URL del endpoint. Tiene que empezar por https:// y ser pública: se rechazan las direcciones de redes privadas, las propias direcciones de Sealsimple y las URL con nombre de usuario y contraseña.
  4. Si quieres, añade un Nombre, elige los Eventos (de entrada están todos marcados) y pulsa Añadir webhook.
  5. Copia la Clave de firma que aparece y pulsa Enviar evento de prueba.

Un espacio de trabajo puede tener hasta 10 webhooks.

Eventos

  • document.sent: Documento enviado
  • document.viewed: Abierto por un destinatario, una vez por destinatario
  • document.signed: Firmado por un firmante, una vez por firmante
  • document.completed: Completado: han firmado todos
  • document.declined: Rechazado
  • document.expired: Caducado
  • document.canceled: Cancelado

Qué enviamos

Un POST con un cuerpo JSON: id (el mismo en cada intento, para que puedas descartar duplicados), event, created_at, workspace_id, un document con id, title, status y url y, en los eventos sobre una persona, un recipient con name, email y role. Un documento cancelado tiene el estado voided. El PDF firmado en sí no se envía: obtenlo con la API REST cuando el documento esté completado. El evento de prueba tiene el evento test y un documento y un firmante inventados.

Comprobar la firma

Cada solicitud lleva una cabecera Sealsimple-Signature como t=1700000000,v1=…, junto a Sealsimple-Event y Sealsimple-Delivery. Para comprobarla:

  1. Toma el cuerpo sin procesar de la solicitud, exactamente como llegó.
  2. Lee t (una marca de tiempo Unix en segundos) y v1 de la cabecera.
  3. Calcula el HMAC-SHA256 de t, un punto y el cuerpo, con tu clave de firma completa como clave, en hexadecimal en minúsculas.
  4. Acepta la solicitud solo si el resultado es igual a v1 (compáralo en tiempo constante) y t no tiene más de unos minutos de antigüedad.

En Cómo conectarlo, Comprobar la firma (Node.js) muestra esto como código, con Copiar código. Nueva clave sustituye la clave al instante, así que actualiza tu comprobación justo después.

Reintentos, el registro y la pausa

Responde con un estado 2xx en menos de 10 segundos. Si no, lo volvemos a intentar más tarde, hasta 6 intentos en total a lo largo de un día aproximadamente. No seguimos las redirecciones, y una respuesta 410 detiene los intentos. El Registro de entregas muestra los últimos 50 mensajes con la respuesta de tu endpoint, y Reenviar vuelve a enviar uno.

Tras 20 entregas fallidas seguidas, pausamos el webhook (En pausa por fallos) y enviamos un correo a los propietarios del espacio de trabajo. Corrige el endpoint, vuelve a activar el webhook y reenvía desde el registro lo que necesites. También puedes pausar un webhook con su interruptor: los eventos que ocurran mientras está en pausa no se envían después. Sin Pro, los webhooks se mantienen, pero no envían nada.

¿Hay una API?

Sí, con Pro. Los webhooks avisan a tu sistema cuando pasa algo; la API REST le permite actuar: subir y enviar documentos, y obtener su estado, el PDF firmado y el registro de auditoría. Empieza por Usar la API (en inglés), o consulta todos los endpoints en la documentación de la API (en inglés).

¿Te ha resultado útil este artículo?

Pruébalo con tu próximo contrato.

5 envíos gratis cada mes natural. Sin tarjeta de crédito.

¿Sigues necesitando ayuda?

Pregunta a nuestro asistente en el chat: responde al momento. O escríbenos un correo y una persona te responderá en un día laborable.