Digito

Eventos y payloads

Catálogo de eventos y estructura JSON de las notificaciones de Digito Business.

Selecciona los eventos en la suscripción del equipo y compara los identificadores de event exactamente como se muestran aquí. Los encabezados descriptivos de esta guía no cambian los valores del contrato.

Documentos y destinatarios

eventCuándo ocurre
DOCUMENT_CREATEDSe crea un documento.
DOCUMENT_SENTSe envía a los destinatarios.
DOCUMENT_OPENEDUn destinatario abre el documento por primera vez.
DOCUMENT_SIGNEDUn destinatario firma el documento.
DOCUMENT_RECIPIENT_COMPLETEDUn destinatario completa la acción de su rol, como firmar, aprobar o visualizar.
DOCUMENT_COMPLETEDTodos los destinatarios han completado las acciones requeridas del proceso.
DOCUMENT_REJECTEDUn destinatario rechaza el documento.
DOCUMENT_CANCELLEDSe cancela un documento pendiente o su propietario lo elimina.
DOCUMENT_REMINDER_SENTSe envía un recordatorio a un destinatario.
RECIPIENT_EXPIREDVence el plazo de un destinatario sin que haya firmado o rechazado.

Una apertura no es una firma. Completar la acción de un aprobador o de una persona que solo visualiza tampoco implica una firma criptográfica. Para actuar sobre la finalización del sobre, utiliza DOCUMENT_COMPLETED y confirma su estado por API.

Plantillas

eventCuándo ocurre
TEMPLATE_CREATEDSe crea una plantilla.
TEMPLATE_UPDATEDSe modifica una plantilla.
TEMPLATE_DELETEDSe elimina una plantilla.
TEMPLATE_USEDSe crea un documento a partir de una plantilla.

En los tres primeros eventos, payload.envelopeId identifica la plantilla. En TEMPLATE_USED, identifica el nuevo documento, no la plantilla de origen. No deduzcas el tipo de recurso a partir de los IDs numéricos.

Estructura de una entrega

Todas las notificaciones utilizan estos campos de nivel superior:

CampoTipoContenido
eventstringIdentificador del evento.
payloadobjectDatos del documento o de la plantilla y sus destinatarios.
createdAtstring de fecha y horaMomento de creación del aviso.
webhookEndpointstringURL receptora de la suscripción.

Ejemplo sintético y reducido de DOCUMENT_COMPLETED; se omiten otros campos y los tokens de destinatario:

{
  "event": "DOCUMENT_COMPLETED",
  "payload": {
    "id": 123,
    "envelopeId": "envelope_abcdefhiklmnorst",
    "externalId": "contrato-2026-001",
    "title": "Contrato de servicios.pdf",
    "status": "COMPLETED",
    "completedAt": "2026-10-21T14:30:00.000Z",
    "recipients": [
      {
        "id": 1,
        "envelopeId": "envelope_abcdefhiklmnorst",
        "email": "laura@example.com",
        "name": "Laura Marte",
        "role": "SIGNER",
        "signingStatus": "SIGNED"
      }
    ]
  },
  "createdAt": "2026-10-21T14:30:01.000Z",
  "webhookEndpoint": "https://integracion.example.com/webhooks/digito"
}

Identificadores y campos útiles

Campo de payloadCómo utilizarlo
envelopeIdIdentificador canónico de tipo string para consultar el recurso en la API v2.
idIdentificador numérico de compatibilidad; no lo uses como ID de ruta de la API v2.
externalIdReferencia de tu integración, cuando se haya definido; puede ser null.
statusEstado del recurso en el aviso: DRAFT, PENDING, COMPLETED, REJECTED o CANCELLED.
createdAt, updatedAtFechas de creación y actualización del recurso; son distintas de la fecha del aviso.
completedAt, deletedAtFechas de finalización o eliminación, cuando existan.
teamIdEquipo asociado al recurso; comprueba el alcance con la clave de ese equipo.
templateIdReferencia numérica de la plantilla de origen, cuando corresponda; puede ser null.
recipientsDestinatarios, roles y estados individuales.
RecipientRepresentación de compatibilidad de la misma lista; no la proceses una segunda vez.
documentMetaMetadatos del documento, cuando existan.

Cada destinatario puede incluir envelopeId, role, readStatus, sendStatus, signingStatus, signedAt, expiresAt y rejectionReason. Usa su envelopeId para relacionarlo con el sobre; las referencias numéricas de documento o plantilla pueden ser nulas según el tipo de recurso.

El payload puede contener correos, nombres, valores de formularios y tokens de acceso. Conserva solo los campos necesarios y restringe quién puede consultar las entregas.

Entregas repetidas y orden de procesamiento

No asumas que cada entrega llegará una sola vez ni que llegará en el mismo orden en que procesas otras. Un reenvío puede repetir un aviso ya aceptado. Guarda una huella de la entrega y utiliza operaciones idempotentes para evitar duplicar correos, archivos o actualizaciones.

El objeto de nivel superior no documenta un ID único de entrega. No inventes un campo eventId ni uses solo event + envelopeId para deduplicar: un mismo destinatario o sobre puede generar más de un evento del mismo tipo.

Consulta el estado actual del sobre antes de una acción irreversible. Si el recurso fue eliminado, su consulta puede fallar; utiliza el aviso autenticado y tu registro local para reconciliar esa eliminación.