¿Cómo funcionan los webhooks de DIGID para automatizar flujos de firma?

Cuando un firmante completa su proceso, el sistema de la empresa necesita saberlo de inmediato — para activar el siguiente paso, actualizar el estado en su base de datos o notificar al equipo correspondiente. Sin esa notificación automática, la única alternativa es consultar el estado del documento repetidamente hasta que cambie, lo que es ineficiente y difícil de escalar.

Los webhooks de DIGID resuelven eso: cada vez que ocurre un evento relevante en el proceso de firma o verificación de identidad, DIGID hace un POST al endpoint que la empresa configuró con los datos del evento. El sistema de la empresa recibe la notificación, la procesa y actúa.

Los 10 eventos que emite DIGID

DIGID distingue entre dos tipos de eventos: los que corresponden a un firmante concreto y los que corresponden al documento completo.

Eventos de tipo Firmante

Notifican el progreso individual de cada firmante. El payload incluye el IdFirmante además del IdDocumento.

Eventos de tipo Documento

Notifican el estado del documento completo, independientemente de quién firme. El payload no incluye IdFirmante.

Estructura del payload

Los payloads son compactos y consistentes. La diferencia principal entre tipos es la presencia o ausencia de IdFirmante.

Evento de Firmante:

{
  "Notificacion": "Firmante",
  "IdDocumento": 123,
  "IdFirmante": 456,
  "Estatus": "KYC Exitoso",
  "Fecha": "2026-06-23T18:31:12.000000Z"
}

{
  "Notificacion": "Firmante",
  "IdDocumento": 123,
  "IdFirmante": 456,
  "Estatus": "KYC Exitoso",
  "Fecha": "2026-06-23T18:31:12.000000Z"
}

{
  "Notificacion": "Firmante",
  "IdDocumento": 123,
  "IdFirmante": 456,
  "Estatus": "KYC Exitoso",
  "Fecha": "2026-06-23T18:31:12.000000Z"
}

Evento de Documento:

{
  "Notificacion": "Documento",
  "IdDocumento": 123,
  "Estatus": "PROCESO CONCLUIDO",
  "Fecha": "2026-06-23T18:40:00.000000Z"
}

{
  "Notificacion": "Documento",
  "IdDocumento": 123,
  "Estatus": "PROCESO CONCLUIDO",
  "Fecha": "2026-06-23T18:40:00.000000Z"
}

{
  "Notificacion": "Documento",
  "IdDocumento": 123,
  "Estatus": "PROCESO CONCLUIDO",
  "Fecha": "2026-06-23T18:40:00.000000Z"
}

La regla para procesar correctamente: distinguir siempre primero por Notificacion y después por Estatus. Los eventos de tipo Documento no incluyen IdFirmante — intentar leerlo en esos casos devuelve nulo.

La secuencia típica de eventos

Para un documento con un solo firmante que completa el proceso sin incidencias, el orden de llegada aproximado es:

Con varios firmantes, los pasos 2 a 5 se repiten por cada uno. PROCESO CONCLUIDO se emite una sola vez, cuando todos han firmado.

Variantes frecuentes:

• Si el KYC falla: llega KYC Fallido; si el firmante reintenta, Reinicio KYC y el ciclo continúa

• Si se rechaza al firmante: Documentación Rechazada

• Si se cancela el documento: Documento → Cancelado interrumpe el flujo en cualquier punto

Lo que el equipo de desarrollo necesita saber

DIGID no reintenta los webhooks

Si el endpoint de la empresa no responde o devuelve un error, el evento no se vuelve a enviar. Esto tiene una implicación directa: el endpoint debe responder 2xx de forma inmediata, sin esperar a que la lógica de procesamiento termine. Si el procesamiento tarda, la práctica correcta es responder 200 OK al recibir el evento y encolar la lógica para procesarla de forma asíncrona.

Si un evento se pierde por un fallo temporal del endpoint, la forma de recuperarlo es consultando el estado del documento directamente a través de la API REST — los endpoints de consulta de documento y detalles de firmantes devuelven el estado actual en cualquier momento.

Idempotencia

La red puede entregar el mismo evento más de una vez, o los eventos pueden llegar en orden distinto al esperado. El endpoint receptor debe manejar ambas situaciones:

• Deduplicación: usar la combinación IdDocumento + IdFirmante + Estatus + Fecha como clave única para no procesar dos veces el mismo evento

• No asumir orden: validar el estado contra el modelo propio antes de actuar, en lugar de depender del orden de llegada

Validación de origen

Los webhooks de DIGID no incluyen firma criptográfica en el payload. Para verificar que el POST proviene de DIGID y no de una fuente externa, se recomienda:

• Restringir por IP de origen: 2607:5300:205:200::4685

• Usar una URL de webhook con un segmento secreto difícil de adivinar

Plantilla mínima del receptor

Casos de uso típicos con webhooks

Activar el siguiente paso del flujo: cuando llega PROCESO CONCLUIDO, el sistema descarga el documento firmado y lo vincula al expediente del cliente, activa la cuenta, genera la factura o desencadena el siguiente paso del proceso interno.

Notificar en tiempo real: cuando llega Documento Firmado para un firmante específico, el sistema puede notificar al área correspondiente o al siguiente firmante en la cadena.

Detectar KYC fallido: cuando llega KYC Fallido, el sistema puede notificar al operador para que asista al firmante o escale el caso a revisión manual.

Auditoría del proceso: cada evento con su timestamp permite reconstruir la línea de tiempo completa del proceso de firma — cuándo entró cada firmante, cuánto tardó, dónde hubo fricciones.

Preguntas frecuentes

¿Cómo configuro el endpoint de webhook en DIGID? La URL del endpoint se configura en el portal de DIGID o mediante la API. Una vez configurado, DIGID enviará todos los eventos de esa cuenta a esa URL.

¿Puedo tener endpoints distintos para diferentes tipos de eventos? La configuración actual envía todos los eventos al mismo endpoint. La distinción por tipo de evento se hace en el receptor, usando el campo Notificacion.

¿Qué pasa si mi endpoint estuvo caído y perdí eventos? Como DIGID no reintenta, los eventos perdidos no se recuperan automáticamente. La forma de reconciliar el estado es consultando directamente los endpoints de la API REST: el estado del documento y los detalles de cada firmante reflejan el estado actual en cualquier momento.

¿Los webhooks de KYC y los de firma llegan al mismo endpoint? Sí. Todos los eventos — tanto los del proceso de KYC como los de firma del documento — llegan al mismo endpoint configurado. El campo Estatus distingue de qué tipo de evento se trata.

¿Hay un entorno de prueba para los webhooks? Sí. El sandbox de DIGID emite los mismos eventos que producción, lo que permite probar el receptor completo antes de salir en vivo.

Automatiza tus flujos con los eventos de DIGID

Con los webhooks de DIGID tu sistema reacciona en tiempo real a cada paso del proceso de firma y verificación de identidad — sin consultas periódicas y sin intervención manual.

Solicita acceso al sandbox y empieza a probar.