Webhooks y firma electrónica: notificaciones automáticas

Si tu empresa firma decenas o cientos de documentos al mes —contratos, actas, facturas, comprobantes de retención— revisar manualmente el estado de cada uno es un desperdicio de tiempo. Ahí entran los webhooks y firma electrónica: la combinación que le permite a tus sistemas enterarse, en el momento exacto, de que un documento fue enviado, visto, firmado o rechazado, sin que nadie tenga que entrar a revisar una bandeja de entrada.

En este artículo explicamos qué es un webhook, cómo se integra a un flujo de firma electrónica en Ecuador, qué eventos suelen dispararse, y cómo esto se relaciona con la validez legal que exige la Ley de Comercio Electrónico, Firmas Electrónicas y Mensajes de Datos.

Qué es un webhook (y por qué no es lo mismo que revisar manualmente)

Un webhook es una notificación automática que un sistema envía a otro cuando ocurre un evento específico. En lugar de que tu aplicación pregunte constantemente "¿ya se firmó el documento?" (lo que se conoce como polling), el servicio de firma electrónica le avisa a tu sistema apenas ese evento sucede, mediante una petición HTTP a una URL que tú configuras.

La diferencia práctica es enorme: sin webhooks, tu equipo tiene que abrir el correo o el portal de firmas cada cierto tiempo para ver si algo cambió. Con webhooks, tu ERP, tu CRM o tu sistema contable reciben la información al instante y pueden actuar solos: mover el contrato a "firmado", liberar una factura, notificar al cliente, o archivar el documento en el repositorio correcto.

Qué eventos dispara un flujo de firma electrónica

En un proceso típico de firma electrónica orientado a empresas, los eventos más comunes que se notifican vía webhook son:

• Documento enviado a firmar: se generó la solicitud y se notificó al firmante.
• Documento visto/abierto: el firmante ingresó al documento pero aún no firmó.
• Documento firmado: el firmante aplicó su firma electrónica válida.
• Documento rechazado: el firmante decidió no firmar y, según el flujo, puede o no indicar el motivo.
• Documento expirado: venció el plazo configurado para firmar sin que se completara.
• Proceso completado: todos los firmantes requeridos ya firmaron y el documento queda cerrado y sellado.

Cada uno de estos eventos, al llegar como webhook, trae consigo datos como el identificador del documento, la marca de tiempo, el firmante involucrado y, normalmente, un enlace o referencia al archivo final. Esto es lo que le permite a un sistema externo actuar sin intervención humana.

Webhooks independientemente del formato de firma

En Ecuador, la firma electrónica se puede aplicar con distintos formatos técnicos:

• Archivo .p12: un certificado digital instalado como archivo en el computador del firmante.
• Token criptográfico (USB): el certificado vive en un dispositivo físico que se conecta al equipo.
• Firma en la nube: el certificado se resguarda en un servidor seguro y el firmante lo activa remotamente, sin instalar nada, incluyendo modalidades como FirmaEC del Registro Civil.

Para efectos de los webhooks, el formato del certificado es transparente: lo que le interesa a tu sistema es el evento (firmado, rechazado, etc.), no si el firmante usó un token físico o una firma en la nube. Eso simplifica mucho la integración, porque un mismo endpoint puede recibir notificaciones sin importar cómo cada firmante prefirió firmar.

Validez legal: lo que respalda cada notificación

La firma electrónica en Ecuador tiene el mismo valor jurídico que una firma manuscrita gracias a la Ley de Comercio Electrónico, Firmas Electrónicas y Mensajes de Datos, siempre que el certificado provenga de una entidad de certificación de información acreditada. En el país, la acreditación y supervisión de estas entidades corresponde a la ARCOTEL (Agencia de Regulación y Control de las Telecomunicaciones), que mantiene el registro de las entidades autorizadas para emitir certificados de firma electrónica.

Que un webhook te avise "documento firmado" no es solo una conveniencia operativa: detrás de ese evento hay un certificado emitido por una entidad acreditada, con sello de tiempo y trazabilidad, lo que le da respaldo legal al documento resultante. Por eso es importante trabajar con proveedores que integren certificados de entidades reconocidas y no con soluciones que simulan una firma sin sustento criptográfico real.

Webhooks, SRI y procesos contables

Muchas empresas ecuatorianas necesitan que la firma de documentos se sincronice con sus procesos tributarios y contables. Aunque la firma electrónica de comprobantes ante el SRI sigue su propio esquema de autorización, es común que las empresas quieran encadenar eventos: por ejemplo, que apenas se firme un contrato o un acta de entrega-recepción, el sistema contable reciba la notificación automáticamente y genere el comprobante correspondiente, o que se notifique al área de facturación para continuar el proceso.

Si tu empresa además de firmar documentos necesita resolver la facturación electrónica del grupo, esa parte del proceso la cubre azur.com.ec, empresa hermana enfocada en soluciones de facturación. Los webhooks de firma pueden ser el punto de partida que dispare esos flujos posteriores.

Seguridad: cómo deben viajar los webhooks

Un webhook mal implementado es un riesgo de seguridad, porque cualquiera podría enviar una petición falsa a tu endpoint simulando que un documento fue firmado. Por eso, una integración seria de webhooks y firma electrónica debe incluir:

• Conexión HTTPS obligatoria entre el proveedor de firma y tu servidor.
• Firma o token de verificación (HMAC) en cada payload, para que tu sistema confirme que la notificación viene realmente del proveedor y no fue falsificada.
• Reintentos automáticos si tu endpoint no responde, para no perder eventos por caídas temporales.
• Idempotencia, es decir, que recibir el mismo evento dos veces no duplique acciones en tu sistema (por ejemplo, usando el identificador único del documento y del evento).

Casos de uso frecuentes en empresas ecuatorianas

• Departamentos legales: notificar automáticamente cuando un contrato queda completamente firmado por todas las partes, sin monitoreo manual.
• Recursos humanos: disparar el archivo automático de un contrato laboral firmado en el legajo del colaborador dentro del sistema interno.
• Inmobiliarias y constructoras: avisar al equipo comercial en tiempo real cuando un cliente firma una promesa de compraventa.
• Empresas con integraciones vía API: conectar la firma electrónica directamente a un CRM, ERP o plataforma de gestión documental propia, como parte de un flujo más amplio de automatización.

Cómo empezar a integrar webhooks de firma electrónica

En términos generales, integrar webhooks a tu flujo de firma implica: definir el endpoint (URL) donde vas a recibir las notificaciones, elegir qué eventos te interesa escuchar (no siempre hace falta suscribirse a todos), validar la autenticidad de cada notificación recibida, y programar la lógica de negocio que se ejecuta en tu sistema al recibir cada evento. Si tu equipo técnico ya trabaja con APIs, la curva de aprendizaje suele ser corta.

Preguntas frecuentes

¿Los webhooks funcionan igual con firma .p12, token o firma en la nube?

Sí. El webhook notifica el evento del proceso de firma (enviado, visto, firmado, rechazado), independientemente del formato técnico del certificado que use cada firmante.

¿Necesito conocimientos avanzados de programación para usar webhooks?

Se requiere que tu equipo técnico o el proveedor que te apoya sepa recibir peticiones HTTP en un endpoint y validarlas. No es una integración compleja para un desarrollador con experiencia en APIs.

¿Un webhook reemplaza la validez legal de la firma?

No. El webhook es solo el mecanismo de notificación. La validez legal de la firma la da el certificado emitido por una entidad de certificación acreditada por ARCOTEL, conforme a la Ley de Comercio Electrónico, Firmas Electrónicas y Mensajes de Datos.

¿Puedo recibir notificaciones sin usar webhooks?

Sí, mediante consultas periódicas (polling) al estado del documento, pero es menos eficiente y más lento que recibir la notificación en tiempo real.

¿Qué pasa si mi servidor está caído cuando llega el webhook?

Un buen proveedor implementa reintentos automáticos durante un período determinado, para asegurar que la notificación llegue una vez tu servidor vuelva a estar disponible.

¿Cuánto cuesta integrar webhooks de firma electrónica?

Depende del plan y del volumen de documentos de tu empresa. Revisa los detalles y rangos actualizados en nuestra sección de precios.

Automatiza tus notificaciones de firma

Dejar de revisar manualmente si un documento fue firmado es uno de los primeros pasos hacia una operación más ágil. Si tu empresa necesita integrar webhooks y firma electrónica a su sistema actual, cotiza o solicita tu firma electrónica aquí y conversemos sobre tu flujo específico.

Volver al inicio de Firmas.com.ec