Webhooks de Talana

Los Webhooks de Talana permiten integraciones ágiles y eficientes al ofrecer notificaciones en tiempo real de los eventos críticos del sistema, evitando el polling constante hacia nuestra API.

¿Qué son y cómo funcionan?

Los webhooks funcionan como una notificación de empuje (push notification). Cuando ocurre un evento en Talana (por ejemplo, la creación, modificación o eliminación de un recurso), nuestro sistema realiza una solicitud HTTP POST al endpoint que hayas definido previamente, con Content-Type: application/json.

El cuerpo del mensaje (payload) incluye la información detallada del evento, permitiendo que su aplicación procese los cambios de forma instantánea.

Los webhooks cuentan con un timeout configurado de 600 segundos (10 minutos) para la recepción de respuestas por parte de los sistemas integradores. Esto con el objetivo de mejorar la estabilidad y confiabilidad del procesamiento de eventos, especialmente en escenarios donde existen demoras operacionales, alta concurrencia o procesos downstream más extensos.

Reintentos: los webhooks de Talana no cuentan con reintentos automáticos. Si tu endpoint responde con un código HTTP >= 400, el error queda registrado en los logs de Talana, pero el evento no se reenvía. Se recomienda que tu integración devuelva 2xx rápidamente y procese el payload de forma asíncrona si es necesario.

Autenticación y seguridad

La seguridad de los datos es una prioridad para Talana. Por ello, todos los endpoints que reciban notificaciones deben implementar Autenticación Básica (Basic Auth).

Durante la configuración, deberás proporcionar las credenciales (usuario y contraseña), las cuales se incluirán en el encabezado de la solicitud HTTP.

Authorization: Basic (username:password)

Importante: Este método permite que tu servicio verifique que la notificación proviene legítimamente de la plataforma de Talana.

Cómo solicitar

Comunícate con el SAC para que puedan derivarte al equipo de Back.
El equipo de Back configurará el webhook que necesites, según los modelos que se muestran más abajo.
Se te comunicará cuando el webhook esté configurado.

Estructura del mensaje

Todos los eventos comparten esta estructura de envoltura (envelope):

{
  "type": "<nombre del modelo>",
  "event": "created | modified | deleted",
  "companyId": 123,
  "instance": { ... }
}

Campo	Tipo	Descripción
`type`	`string`	Nombre del modelo que disparó el evento (ej: `"persona"`)
`event`	`string`	`"created"`, `"modified"` o `"deleted"`
`companyId`	`integer`	ID interno de la empresa en Talana
`instance`	`object`	Objeto serializado con todos los campos del modelo

Eventos disponibles

Modelo	Eventos disponibles	Descripción breve
`persona`	`created`, `modified`, `deleted`	Cambios en la ficha del trabajador
`personaEmpresa`	`created`, `modified`, `deleted`	Contrato / relación laboral del trabajador con la empresa
`vacacionesSolicitud`	`created`, `modified`, `deleted`	Solicitudes y cambios de vacaciones
`razonSocial`	`created`, `modified`, `deleted`	Cambios en los datos de la razón social
`personaAusencia`	`created`, `modified`, `deleted`	Creación, modificación o eliminación de ausencias
`centroCosto`	`created`, `modified`, `deleted`	Actualizaciones en centros de costo
`sucursal`	`created`, `modified`, `deleted`	Cambios en sucursales
`unidadOrganizacional`	`created`, `modified`, `deleted`	Cambios en gerencias o áreas
`documento`	`created`, `modified`, `deleted`	Creación, modificación o eliminación de documentos
`SigningRequest`	`created`, `modified`, `deleted`	Eventos del proceso de firma digital (a nivel de solicitud)
`SigningRequestDetail`	`created`	Cambios de estado por firmante dentro de una solicitud de firma

Modelos de Webhooks

Cada webhook incluye en el campo instance un objeto JSON con la información del modelo afectado. A continuación se detallan los modelos disponibles.

1. `persona` — Trabajador

Disparado cuando se crea, modifica o elimina un trabajador.

{
  "id": 1234,
  "fechaCreacion": "2024-01-15T10:30:00Z",
  "rut": "12345678-9",
  "nombre": "Juan",
  "apellidoPaterno": "González",
  "apellidoMaterno": "Pérez",
  "sexo": "M",
  "fechaNacimiento": "1990-05-20",
  "nacionalidad": 1,
  "username": "[email protected]",
  "email": "[email protected]",
  "anexo": "123",
  "permisos": [
    { "nombre": "Permiso A", "vigente": true }
  ],
  "detalles": [
    {
      "id": 5678,
      "foto": "url/to/photo.jpg",
      "idiomas": [{ "id": 0, "nombre": "string" }],
      "codigoUbicacion": "CL-RM",
      "fechaCreacion": "2024-01-15T10:30:00Z",
      "validoDesde": "2024-01-15",
      "email": "[email protected]",
      "emailPersonal": "[email protected]",
      "telefono": "+56222345678",
      "celular": "+56912345678",
      "direccionCalle": "Av. Principal",
      "direccionNumero": "123",
      "direccionDepartamento": "4B",
      "nivelEducacional": "sin info",
      "colegio": "string",
      "institucionEstudiosSuperiores": "string",
      "profesion": "Ingeniero",
      "observaciones": "string",
      "contactosDeEmergencia": "string",
      "sangre": "ap",
      "alergias": "string",
      "discapacidades": "string",
      "enfermedades_cronicas": "string",
      "medicamentos_permanentes": "string",
      "direccionComuna": 0,
      "direccionCiudad": 10,
      "estadoCivil": "soltero"
    }
  ],
  "empresa": {
    "id": 99,
    "fechaCreacion": "2020-01-01T00:00:00Z",
    "nombre": "Empresa Demo S.A.",
    "vigente": true,
    "url": "string",
    "logo": "string",
    "logoWebPublica": "string",
    "ordenWebPublica": 0,
    "esPrueba": false,
    "tier": "tier2",
    "tags": {},
    "company_group": 0,
    "calendarioDeFeriados": 0,
    "pais": "string"
  },
  "externalReference": [
    { "localId": 1234, "remoteId": "EXT-001", "model": "persona", "integration": "MiIntegracion" }
  ],
  "userDefinedFields": [
    {
      "id": 1,
      "fieldName": "Campo personalizado",
      "userDefinedFieldValue": [{ "id": 10, "value": "valor" }]
    }
  ]
}

Campo	Tipo	Descripción
`id`	`integer`	ID único del trabajador
`fechaCreacion`	`datetime`	Fecha/hora de creación
`rut`	`string`	RUT/DNI del trabajador
`nombre`	`string`	Nombre(s)
`apellidoPaterno`	`string`	Apellido paterno
`apellidoMaterno`	`string`	Apellido materno
`sexo`	`string`	`"M"` Masculino, `"F"` Femenino, `"N"` No especificado
`fechaNacimiento`	`date`	Fecha de nacimiento (`YYYY-MM-DD`)
`nacionalidad`	`integer`	ID de país de nacionalidad
`username`	`string`	Nombre de usuario (login)
`email`	`string`	Correo corporativo
`anexo`	`string`	Anexo telefónico
`permisos`	`array`	Lista de permisos asignados
`detalles`	`array`	Datos personales adicionales (ver tabla abajo)
`empresa`	`object`	Empresa a la que pertenece
`externalReference`	`array\|null`	Referencia a IDs externos de integración. Es `null` si no hay referencias configuradas (no `[]`)
`userDefinedFields`	`array`	Campos personalizados definidos por la empresa. `[]` si no hay UDFs configurados

Sub-objeto detalles:

Campo	Tipo	Descripción
`foto`	`string`	URL de la foto de perfil
`idiomas`	`array`	Idiomas que domina
`codigoUbicacion`	`string`	Código de la ubicación geográfica
`validoDesde`	`date`	Fecha desde la que el registro es válido
`email`	`string`	Correo (laboral, dentro de detalles)
`emailPersonal`	`string`	Correo personal
`telefono`	`string`	Teléfono fijo
`celular`	`string`	Número de celular
`direccionCalle`	`string`	Calle de residencia
`direccionNumero`	`string`	Número de la dirección
`direccionDepartamento`	`string`	Departamento/Piso
`nivelEducacional`	`string`	Nivel educacional
`colegio`	`string`	Colegio
`institucionEstudiosSuperiores`	`string`	Institución de estudios superiores
`profesion`	`string`	Profesión
`observaciones`	`string`	Observaciones
`contactosDeEmergencia`	`string`	Contactos de emergencia
`sangre`	`string`	Grupo sanguíneo
`alergias`	`string`	Alergias
`discapacidades`	`string`	Discapacidades
`enfermedades_cronicas`	`string`	Enfermedades crónicas
`medicamentos_permanentes`	`string`	Medicamentos permanentes
`direccionComuna`	`integer`	ID de comuna
`direccionCiudad`	`integer`	ID de ciudad
`estadoCivil`	`string`	`"soltero"`, `"casado"`, `"divorciado"`, `"viudo"`, `"AUC"`

2. `personaEmpresa` — Contrato de trabajo

Disparado cuando se crea, modifica o elimina un contrato (o anexo de contrato). Modelo complementario a persona: contiene la relación del trabajador con la empresa.

{
  "id": 9999,
  "empleado": 1234,
  "codigo": "EMP-001",
  "fechaCreacion": "2024-01-15T10:30:00Z",
  "fechaModificacion": "2024-06-01T09:00:00Z",
  "tipoContrato": 2,
  "tipoContratoDetails": { "id": 2, "nombre": "Contrato Indefinido" },
  "empleadorRazonSocial": 5,
  "cargo": "Analista de Sistemas",
  "fechaContratacion": "2023-01-01",
  "desde": "2023-01-01",
  "hasta": null,
  "unidadOrganizacional": 3,
  "unidadOrganizacionalDetails": {
    "id": 3, "parent": 1, "nombre": "Tecnología", "codigo": "TEC", "externalReference": []
  },
  "sucursal": { "id": 7, "nombre": "Casa Central" },
  "centroCosto": { "id": 12, "codigo": "CC-01", "nombre": "IT" },
  "jornada": 1,
  "horasDeLaJornada": 45,
  "sindicato": null,
  "jefe": 500,
  "esPensionado": "N",
  "isapre": 1,
  "montoPactadoIsapre": 3.0,
  "montoPactadoIsapreMoneda": "UF",
  "afp": 3,
  "sueldoBase": 1500000,
  "sueldoBanco": 1,
  "sueldoCuentaCorriente": "12345678",
  "sueldoCuentaCorrienteTipo": "cuenta corriente",
  "sueldoTipoPago": "transferencia",
  "asignacionMovilizacion": 50000,
  "asignacionColacion": 50000,
  "vacacionesReconocidoDesde": "2023-01-01",
  "finiquitado": false,
  "motivoEgreso": null,
  "INE": null,
  "externalReference": [],
  "userDefinedFields": { "campo1": "valor1" }
}

Campo	Tipo	Descripción
`id`	`integer`	ID del contrato
`empleado`	`integer`	ID del trabajador
`codigo`	`string`	Código interno de la empresa
`fechaCreacion`	`datetime`	Fecha de creación del registro
`fechaModificacion`	`datetime`	Fecha de última modificación
`tipoContrato`	`integer`	ID del tipo de contrato
`tipoContratoDetails`	`object`	`{ id, nombre }` del tipo de contrato
`empleadorRazonSocial`	`integer`	ID de la razón social empleadora
`cargo`	`string`	Cargo del trabajador
`fechaContratacion`	`date`	Fecha oficial de contratación
`desde`	`date`	Inicio de vigencia del contrato
`hasta`	`date\|null`	Fin de vigencia (`null` si es indefinido)
`unidadOrganizacional`	`integer`	ID de la unidad organizacional
`unidadOrganizacionalDetails`	`object`	Objeto expandido de la unidad organizacional
`sucursal`	`object`	Sucursal asignada (expandida)
`centroCosto`	`object`	Centro de costo asignado (expandido)
`jornada`	`integer`	ID de la jornada de trabajo
`horasDeLaJornada`	`integer`	Horas semanales de la jornada
`sindicato`	`integer\|null`	ID del sindicato
`jefe`	`integer\|null`	ID del jefe directo
`esPensionado`	`string`	`"N"` No, `"S"` Sí (sin AFP), `"C"` Sí (con AFP)
`isapre`	`integer\|null`	ID de la ISAPRE
`montoPactadoIsapre`	`number\|null`	Monto pactado en ISAPRE
`montoPactadoIsapreMoneda`	`string`	Moneda: `"UF"`, `"$"`, `"%"`, etc.
`afp`	`integer\|null`	ID de la AFP
`sueldoBase`	`number`	Sueldo base
`sueldoBanco`	`integer`	ID del banco de pago
`sueldoCuentaCorriente`	`string`	Número de cuenta
`sueldoCuentaCorrienteTipo`	`string`	Tipo de cuenta
`sueldoTipoPago`	`string`	Forma de pago (ej: `"transferencia"`)
`asignacionMovilizacion`	`number`	Asignación de movilización
`asignacionColacion`	`number`	Asignación de colación
`vacacionesReconocidoDesde`	`date`	Fecha desde la cual se reconocen vacaciones
`finiquitado`	`boolean`	Si el contrato está finiquitado
`motivoEgreso`	`object\|null`	Motivo de egreso (si aplica)
`INE`	`object\|null`	Código INE asociado
`externalReference`	`array`	Referencias externas de integración
`userDefinedFields`	`object`	Campos personalizados (`{ nombre_campo: valor }`)

3. `razonSocial` — Razón Social

Disparado cuando se crea, modifica o elimina una razón social de la empresa.

{
  "id": 5,
  "empresa": 99,
  "rut": "76543210-9",
  "razonSocial": "Empresa Demo S.A.",
  "nombreComercial": "Empresa Demo",
  "giro": "Servicios de Tecnología",
  "direccion": "Av. Providencia 1234, Santiago",
  "calleCasaMatriz": "Av. Providencia",
  "numeroCasaMatriz": "1234",
  "regionCasaMatriz": 15,
  "comunaCasaMatriz": 120,
  "cajaCompensacion": 1,
  "mutual": 2,
  "mutualPorcentajeDescuento": 0.0093,
  "mutualCodigoSucursal": "001",
  "comuna": 120,
  "telefono": "+5622123456",
  "bancoPagoNomina": 1,
  "cuentaCorrientePagoNomina": "12345678",
  "representanteLegal": "Pedro Soto",
  "rutRepresentanteLegal": "9876543-2",
  "representanteEmail": "[email protected]",
  "representanteTelefono": "+56912345678",
  "logo": "url/to/logo.png",
  "fechaCreacion": "2020-01-01T00:00:00Z",
  "empresa_est": false,
  "appeal_days_for_rejected_requests": 0,
  "appeal_area_for_rejected_requests": "string"
}

Campo	Tipo	Descripción
`id`	`integer`	ID de la razón social
`empresa`	`integer`	ID de la empresa
`rut`	`string`	RUT/RUC de la razón social
`razonSocial`	`string`	Nombre legal
`nombreComercial`	`string\|null`	Nombre de fantasía
`giro`	`string\|null`	Giro o actividad económica
`direccion`	`string`	Dirección legal
`calleCasaMatriz`	`string\|null`	Calle de casa matriz
`numeroCasaMatriz`	`string\|null`	Número de casa matriz
`regionCasaMatriz`	`integer\|null`	ID de región
`comunaCasaMatriz`	`integer\|null`	ID de comuna
`cajaCompensacion`	`integer\|null`	ID de caja de compensación
`mutual`	`integer\|null`	ID de mutual de seguridad
`mutualPorcentajeDescuento`	`float`	Tasa de cotización de accidentes (ej: `0.0093`)
`mutualCodigoSucursal`	`string\|null`	Código de sucursal de la mutual
`comuna`	`integer\|null`	ID de comuna
`telefono`	`string`	Teléfono
`bancoPagoNomina`	`integer\|null`	ID del banco para nóminas
`cuentaCorrientePagoNomina`	`string`	Número de cuenta para nóminas
`representanteLegal`	`string`	Nombre del representante legal
`rutRepresentanteLegal`	`string`	RUT del representante legal
`representanteEmail`	`string\|null`	Email del representante legal
`representanteTelefono`	`string\|null`	Teléfono del representante legal
`logo`	`string`	URL del logo
`fechaCreacion`	`datetime`	Fecha de creación
`empresa_est`	`boolean`	Si es una empresa de servicios transitorios (EST)
`appeal_days_for_rejected_requests`	`integer\|null`	Días de plazo para apelar solicitudes rechazadas
`appeal_area_for_rejected_requests`	`string\|null`	Área a cargo de apelaciones

Campos excluidos del webhook (existen en el modelo pero no se envían): formaDePagoDeGratificacion, formaDePagoDeMovilizacionYColacion, tipoDeEmpresa, vigente, autor, principal.

4. `sucursal` — Sucursal

Disparado cuando se crea, modifica o elimina una sucursal.

{
  "id": 7,
  "empresa": 99,
  "nombre": "Casa Central",
  "desde": "2020-01-01",
  "fechaCreacion": "2020-01-01T00:00:00Z",
  "creadoPor": 1,
  "vigente": true,
  "direccionCalle": "Av. Providencia",
  "direccionNumero": "1234",
  "direccionDepartamento": "Piso 5",
  "direccionComuna": 120,
  "direccionCiudad": 15,
  "telefono": "+5622123456",
  "location": "POINT (-70.6483 -33.4372)",
  "location_parseado": { "lat": -33.4372, "lng": -70.6483 },
  "rango": 100,
  "beacons": ["uuid-beacon-1"],
  "timezone": "America/Santiago",
  "externalReference": []
}

Campo	Tipo	Descripción
`id`	`integer`	ID de la sucursal
`empresa`	`integer`	ID de la empresa
`nombre`	`string`	Nombre de la sucursal
`desde`	`date`	Fecha de inicio de vigencia
`fechaCreacion`	`datetime`	Fecha de creación
`creadoPor`	`integer`	ID del trabajador que creó la sucursal
`vigente`	`boolean`	Si la sucursal está activa
`direccionCalle`	`string`	Calle
`direccionNumero`	`string`	Número
`direccionDepartamento`	`string`	Departamento/Piso
`direccionComuna`	`integer\|null`	ID de la comuna
`direccionCiudad`	`integer\|null`	ID de la ciudad
`telefono`	`string`	Teléfono
`location`	`string\|null`	Coordenadas en formato WKT (`POINT (lng lat)`)
`location_parseado`	`object\|null`	Coordenadas como `{ "lat": float, "lng": float }`
`rango`	`integer`	Radio en metros para control de asistencia geolocalizada
`beacons`	`array`	Lista de identificadores de beacons asociados
`timezone`	`string\|null`	Zona horaria (ej: `"America/Santiago"`)
`externalReference`	`array`	Referencias externas de integración

5. `vacacionesSolicitud` — Solicitud de Vacaciones

Disparado cuando se crea, modifica o elimina una solicitud de vacaciones.

{
  "id": 8888,
  "empleado": 1234,
  "vacacionesDesde": "2024-07-01",
  "numeroDias": 15,
  "jornada": "M",
  "mediosDias": false,
  "vacacionesHasta": "2024-07-21",
  "vacacionesRetorno": "2024-07-22",
  "aprobada": "A",
  "aprobadaPor": 500,
  "creadaPor": 1234,
  "tipoVacaciones": 1,
  "fechaAprobacion": "2024-06-20T14:00:00Z",
  "fechaCreacion": "2024-06-18T09:00:00Z",
  "read_person": true,
  "read_boss": true,
  "type": "holidays",
  "detallesTrabajador": { "...": "mismo formato que instance de persona" },
  "externalReference": []
}

Campo	Tipo	Descripción
`id`	`integer`	ID de la solicitud
`empleado`	`integer`	ID del trabajador
`vacacionesDesde`	`date`	Fecha de inicio de vacaciones
`numeroDias`	`integer`	Número de días solicitados
`jornada`	`string`	`"M"` (Mañana) o `"T"` (Tarde), para medio día
`mediosDias`	`boolean`	Si la solicitud es de medio día
`vacacionesHasta`	`date`	Fecha de término de vacaciones
`vacacionesRetorno`	`date\|null`	Fecha de retorno al trabajo
`aprobada`	`string`	`"A"` Aprobada, `"R"` Rechazada, `"P"` Pendiente, `"O"` Esperando 2ª aprobación
`aprobadaPor`	`integer\|null`	ID del trabajador que aprobó
`creadaPor`	`integer\|null`	ID del trabajador que creó la solicitud
`tipoVacaciones`	`integer`	ID del tipo de vacaciones (ej: normales, progresivos)
`fechaAprobacion`	`datetime\|null`	Fecha y hora de aprobación
`fechaCreacion`	`datetime`	Fecha de creación de la solicitud
`read_person`	`boolean`	Si el trabajador leyó la notificación
`read_boss`	`boolean`	Si el jefe leyó la notificación
`type`	`string`	Tipo de solicitud (ej: `"holidays"`)
`detallesTrabajador`	`object`	Objeto completo del trabajador (mismo formato que `persona`)
`externalReference`	`array`	Referencias externas de integración

6. `personaAusencia` — Ausencia / Licencia

Disparado cuando se crea, modifica o elimina una ausencia o licencia médica.

{
  "id": 7777,
  "empleado": 1234,
  "fechaDesde": "2024-06-01",
  "numeroDias": 7,
  "fechaHasta": "2024-06-07",
  "aprobada": true,
  "aprobadaPor": 500,
  "fechaAprobacion": "2024-06-01",
  "tipoAusencia": 1,
  "documentacion": "url/to/licencia.pdf",
  "rebajaSalario": true,
  "esContinuacion": false,
  "creadoPor": 500,
  "fechaCreacion": "2024-06-01T08:00:00Z",
  "fechaRetorno": "2024-06-08",
  "numeroLicencia": "LIC-2024-001",
  "medicoLicencia": "Dr. Pedro González",
  "horaDesde": "09:00:00",
  "numeroHoras": 8,
  "numeroMinutos": 0,
  "horaHasta": "17:00:00",
  "motivo": "Enfermedad común",
  "mediosDias": false,
  "detallesTrabajador": { "...": "mismo formato que instance de persona" },
  "externalReference": []
}

Campo	Tipo	Descripción
`id`	`integer`	ID de la ausencia
`empleado`	`integer`	ID del trabajador
`fechaDesde`	`date`	Fecha de inicio (inclusiva)
`numeroDias`	`integer`	Número de días de ausencia
`fechaHasta`	`date`	Fecha de término (inclusiva)
`aprobada`	`boolean`	Si está aprobada
`aprobadaPor`	`integer\|null`	ID del aprobador
`fechaAprobacion`	`date\|null`	Fecha de aprobación
`tipoAusencia`	`integer\|null`	ID del tipo de ausencia
`documentacion`	`string\|null`	URL del documento adjunto (ej: licencia médica)
`rebajaSalario`	`boolean`	Si se rebaja el salario
`esContinuacion`	`boolean`	Si es continuación de una licencia anterior
`creadoPor`	`integer\|null`	ID de quien registró la ausencia
`fechaCreacion`	`datetime`	Fecha de creación
`fechaRetorno`	`date\|null`	Fecha de retorno al trabajo
`numeroLicencia`	`string\|null`	Número de la licencia médica
`medicoLicencia`	`string\|null`	Nombre del médico
`horaDesde`	`time\|null`	Hora de inicio (para ausencias horarias)
`numeroHoras`	`integer\|null`	Duración en horas
`numeroMinutos`	`integer\|null`	Duración en minutos
`horaHasta`	`time\|null`	Hora de término
`motivo`	`string\|null`	Descripción del motivo
`mediosDias`	`boolean`	Si es sólo medio día
`detallesTrabajador`	`object`	Objeto completo del trabajador (mismo formato que `persona`)
`externalReference`	`array`	Referencias externas de integración

7. `centroCosto` — Centro de Costo

Disparado cuando se crea, modifica o elimina un centro de costo.

{
  "id": 12,
  "parent": null,
  "empresa": 99,
  "codigo": "CC-IT",
  "nombre": "Tecnología",
  "vigente": true,
  "externalReference": [],
  "user_defined_fields": { "campo1": "valor1" }
}

Campo	Tipo	Descripción
`id`	`integer`	ID del centro de costo
`parent`	`integer\|null`	ID del centro de costo padre (estructura jerárquica)
`empresa`	`integer`	ID de la empresa
`codigo`	`string`	Código del centro de costo
`nombre`	`string`	Nombre del centro de costo
`vigente`	`boolean`	Si está activo
`externalReference`	`array`	Referencias externas de integración
`user_defined_fields`	`object`	Campos personalizados

8. `unidadOrganizacional` — Unidad Organizacional / Gerencia

Disparado cuando se crea, modifica o elimina una unidad organizacional (gerencia, área, departamento).

{
  "id": 3,
  "parent": 1,
  "nombre": "Tecnología",
  "codigo": "TEC",
  "externalReference": [
    { "localId": 3, "remoteId": "UA-003", "model": "unidadOrganizacional", "integration": "MiIntegracion" }
  ]
}

Campo	Tipo	Descripción
`id`	`integer`	ID de la unidad organizacional
`parent`	`integer\|null`	ID de la unidad padre (estructura jerárquica)
`nombre`	`string`	Nombre
`codigo`	`string\|null`	Código alfanumérico
`externalReference`	`array`	Referencias externas de integración

9. `documento` — Documento de Trabajador

Disparado cuando se crea, modifica o elimina un documento en la carpeta de un trabajador.

Nota: este webhook no incluye el archivo adjunto en el payload. En su lugar, entrega una URL desde la cual el documento puede descargarse.

{
  "id": 6666,
  "empleado": 1234,
  "empleado_detalles": {
    "id": 1234,
    "nombre": "Juan",
    "apellidoPaterno": "González",
    "apellidoMaterno": "Pérez",
    "cargo": "",
    "gerencia": "",
    "avatar": "",
    "rut": "12345678-9",
    "full_name": "Juan González Pérez"
  },
  "nombre": "Contrato de Confidencialidad",
  "fechaCreacion": "2024-03-01T10:00:00Z",
  "categoria": "Contratos",
  "puedeVerloElTrabajador": true,
  "adjunto": "https://app.talana.com/remuneraciones/documento/download/abc123",
  "creadoPor": 500,
  "user_defined_fields": {}
}

Campo	Tipo	Descripción
`id`	`integer`	ID del documento
`empleado`	`integer`	ID del trabajador al que pertenece
`empleado_detalles`	`object`	Datos básicos del trabajador (ver tabla abajo)
`nombre`	`string`	Nombre o título del documento
`fechaCreacion`	`datetime`	Fecha de creación
`categoria`	`string`	Categoría del documento (ej: `"Contratos"`, `"Otros Documentos"`)
`puedeVerloElTrabajador`	`boolean`	Si el trabajador puede visualizarlo
`adjunto`	`string`	URL para descargar el archivo adjunto
`creadoPor`	`integer`	ID del trabajador que subió el documento
`user_defined_fields`	`object`	Campos personalizados

Sub-objeto empleado_detalles:

Campo	Tipo	Descripción
`id`	`integer`	ID del trabajador
`nombre`	`string`	Nombre
`apellidoPaterno`	`string`	Apellido paterno
`apellidoMaterno`	`string`	Apellido materno
`cargo`	`string`	Siempre `""` en este webhook — el serializer sobreescribe el getter para retornar vacío
`gerencia`	`string`	Siempre `""` en este webhook — el serializer sobreescribe el getter para retornar vacío
`avatar`	`string`	Siempre `""` en este webhook — el serializer sobreescribe el getter para retornar vacío
`rut`	`string`	RUT del trabajador
`full_name`	`string`	Nombre completo

Nota técnica: el webhook usa PersonaDocumentoSerializer (subclase de PersonaSimpleSerializer) que sobreescribe explícitamente get_cargo, get_gerencia y get_avatar para retornar siempre "". Estos tres campos están presentes en el payload pero nunca traen datos reales — no depender de ellos para lógica de negocio.

10. `SigningRequestDetail` — Detalle de Solicitud de Firma Digital

Disparado cuando cambia el estado de una solicitud de firma dirigida a un trabajador específico.

Importante: los valores dentro del array details se serializan todos como string (incluso booleanos, fechas e IDs), ya que se convierten con str() antes de enviarse. Tu integración debe parsear estos valores en lugar de esperar tipos nativos.

{
  "id": 5555,
  "details": [
    {
      "id": "101",
      "signingRequest": "5555",
      "requestedUser": "1234",
      "signed": "False",
      "status": "P",
      "token": "abc123token",
      "signatureTS": "None",
      "TSASignature": "None",
      "ip": "None",
      "userAgent": "None",
      "passVerification": "None",
      "huella": "",
      "rejection_reason": "None"
    }
  ]
}

Campo	Tipo	Descripción
`id`	`integer`	ID del `SigningRequest` (solicitud padre)
`details`	`array`	Lista con un objeto por cada detalle del firmante
`details[].id`	`string`	ID del `SigningRequestDetail`
`details[].signingRequest`	`string`	ID de la solicitud padre
`details[].requestedUser`	`string`	ID del trabajador al que se solicitó la firma
`details[].signed`	`string`	`"True"` o `"False"`
`details[].status`	`string`	`"P"` Pendiente, `"FR"` Firmando, `"F"` Firmada, `"R"` Rechazada, `"E"` Esperando, `"C"` Cancelada, `"SC"` Programado
`details[].token`	`string`	Token único para acceder al documento a firmar
`details[].signatureTS`	`string`	Timestamp de la firma (`"None"` si no ha firmado)
`details[].TSASignature`	`string`	Sello de tiempo de la firma (TSA), si aplica
`details[].ip`	`string`	IP desde la que se firmó
`details[].userAgent`	`string`	User agent del firmante
`details[].passVerification`	`string`	Verificación de clave, si aplica
`details[].huella`	`string`	Ruta del archivo de huella/hash del documento (`FileField`). `""` si está vacío — no `"None"` como los demás campos
`details[].rejection_reason`	`string`	Motivo de rechazo (`"None"` si no aplica)

Nota técnica: el serializer de details usa model_to_dict(obj) de Django, que incluye FileField (como huella) devolviendo la ruta del archivo como string, o "" si está vacío. El resto de los campos vienen de getters que aplican str() sobre el valor, por eso los None de Python aparecen literalmente como el string "None" — mientras que huella, al venir de model_to_dict, usa "" en su lugar.

11. `SigningRequest` — Solicitud de Firma Digital

Disparado cuando se crea o modifica la solicitud de firma en general (no a un firmante específico).

Nota: este evento no se dispara para documentos de tipo DocumentoLibreria (documentos de biblioteca móvil).

{
  "signingRequest": 5555,
  "documentType": "Contrato o Anexo",
  "documentReference": "9999",
  "requestTS": "2024-06-15T14:00:00Z"
}

Campo	Tipo	Descripción
`signingRequest`	`integer`	ID de la solicitud de firma
`documentType`	`string`	`"Contrato o Anexo"`, `"Documento"`, `"Vacaciones"`, `"Dias Administrativos"`, `"Venta Dias Progresivos"`, `"Liquidacion"`, `"Boleta"`, `"Certificado"`
`documentReference`	`string`	ID del documento referenciado (según el `documentType`)
`requestTS`	`datetime`	Timestamp de creación de la solicitud

Campos comunes

`externalReference`

Específico de integraciones configuradas. Permite mapear IDs de Talana con IDs de sistemas externos (localId, remoteId, model, integration).

`userDefinedFields`

Campos personalizados definidos por cada empresa. La estructura varía según el modelo (array de objetos en persona, objeto plano {campo: valor} en personaEmpresa y centroCosto).

¿Qué son y cómo funcionan?

Autenticación y seguridad

Cómo solicitar

Estructura del mensaje

Eventos disponibles

Modelos de Webhooks

1. persona — Trabajador

2. personaEmpresa — Contrato de trabajo

3. razonSocial — Razón Social

4. sucursal — Sucursal

5. vacacionesSolicitud — Solicitud de Vacaciones

6. personaAusencia — Ausencia / Licencia

7. centroCosto — Centro de Costo

8. unidadOrganizacional — Unidad Organizacional / Gerencia

9. documento — Documento de Trabajador

10. SigningRequestDetail — Detalle de Solicitud de Firma Digital

11. SigningRequest — Solicitud de Firma Digital