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
event | Cuándo ocurre |
|---|---|
DOCUMENT_CREATED | Se crea un documento. |
DOCUMENT_SENT | Se envía a los destinatarios. |
DOCUMENT_OPENED | Un destinatario abre el documento por primera vez. |
DOCUMENT_SIGNED | Un destinatario firma el documento. |
DOCUMENT_RECIPIENT_COMPLETED | Un destinatario completa la acción de su rol, como firmar, aprobar o visualizar. |
DOCUMENT_COMPLETED | Todos los destinatarios han completado las acciones requeridas del proceso. |
DOCUMENT_REJECTED | Un destinatario rechaza el documento. |
DOCUMENT_CANCELLED | Se cancela un documento pendiente o su propietario lo elimina. |
DOCUMENT_REMINDER_SENT | Se envía un recordatorio a un destinatario. |
RECIPIENT_EXPIRED | Vence 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
event | Cuándo ocurre |
|---|---|
TEMPLATE_CREATED | Se crea una plantilla. |
TEMPLATE_UPDATED | Se modifica una plantilla. |
TEMPLATE_DELETED | Se elimina una plantilla. |
TEMPLATE_USED | Se 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:
| Campo | Tipo | Contenido |
|---|---|---|
event | string | Identificador del evento. |
payload | object | Datos del documento o de la plantilla y sus destinatarios. |
createdAt | string de fecha y hora | Momento de creación del aviso. |
webhookEndpoint | string | URL 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 payload | Cómo utilizarlo |
|---|---|
envelopeId | Identificador canónico de tipo string para consultar el recurso en la API v2. |
id | Identificador numérico de compatibilidad; no lo uses como ID de ruta de la API v2. |
externalId | Referencia de tu integración, cuando se haya definido; puede ser null. |
status | Estado del recurso en el aviso: DRAFT, PENDING, COMPLETED, REJECTED o CANCELLED. |
createdAt, updatedAt | Fechas de creación y actualización del recurso; son distintas de la fecha del aviso. |
completedAt, deletedAt | Fechas de finalización o eliminación, cuando existan. |
teamId | Equipo asociado al recurso; comprueba el alcance con la clave de ese equipo. |
templateId | Referencia numérica de la plantilla de origen, cuando corresponda; puede ser null. |
recipients | Destinatarios, roles y estados individuales. |
Recipient | Representación de compatibilidad de la misma lista; no la proceses una segunda vez. |
documentMeta | Metadatos 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.