TuLegajo Developers

TuLegajo Webhooks

Recibí en tu sistema una notificación HTTP cada vez que ocurre algo relevante en TuLegajo.com: altas y bajas de empleados, firma de documentos, respuestas a comunicaciones, licencias y fichadas. Sin consultar la API periódicamente.

Origen
TuLegajo.com → tu URL

Introducción

Un webhook es una solicitud HTTP que TuLegajo envía a una URL de tu sistema cuando ocurre un evento. Vos elegís qué eventos te interesan, qué datos de cada evento querés recibir y con qué nombre de campo; nosotros nos encargamos del resto.

Cómo funciona

  1. 1

    Ocurre un evento en TuLegajo

    Por ejemplo, un empleado firma un recibo. El evento se procesa recién cuando la operación quedó confirmada; si la operación falla, no se notifica nada.

  2. 2

    Se arma el mensaje con los campos que elegiste

    Tomamos los datos del evento, los nombramos como pediste y les sumamos los campos fijos que hayas definido (por ejemplo, un token).

  3. 3

    Enviamos la solicitud HTTP a tu URL

    Con el método que configuraste y Content-Type: application/json. El envío es asíncrono: normalmente llega pocos segundos después del evento.

  4. 4

    Tu sistema responde 2xx

    Cualquier respuesta 2xx en menos de 30 segundos da la entrega por exitosa. Si no, reintentamos (ver Entregas y reintentos).

La configuración la hace el equipo de TuLegajo. No hay una pantalla de autogestión: envianos la información de la sección Información requerida a través de soporte y dejamos los webhooks activos en tu organización.

Formato del envío

Cada webhook se dispara para un evento y envía una solicitud a una URL. Si querés el mismo evento en dos sistemas, se configuran dos webhooks.

Solicitud que recibe tu sistema

Método configuradoDónde viajan los datosNotas
POSTPUTPATCHDELETE
Cuerpo JSONObjeto plano (sin anidar) con un atributo por cada campo elegido. Recomendamos POST.

Headers enviados

HeaderValor
Content-Typeapplication/json

No es posible agregar headers personalizados (por ejemplo Authorization). Para autenticar los envíos, ver Seguridad.

Ejemplo — POST
POST /webhooks/tulegajo HTTP/1.1
Host: erp.ejemplo.com
Content-Type: application/json

{
  "cuil": "20-12345678-9",
  "nombre": "Juan",
  "apellido": "Pérez",
  "legajo": "1234",
  "conforme": true,
  "periodoLote": "09-2026"
}
El mensaje no indica el evento por sí solo. Solo viajan los campos que elegiste. Si usás la misma URL para varios eventos, agregá un campo fijo como "evento": "alta_empleado" para distinguirlos.

Campos comunes

Todos los eventos se refieren a un empleado, así que comparten estos campos. Cada evento indica cuáles admite. Por defecto, cada campo llega con el nombre que figura acá; si tu sistema espera otro nombre de atributo, indicalo al pedir el webhook.

Datos del empleado

cuilstring
CUIL del empleado. Es el mismo identificador que usa la API (/empleados/{cuil}).
nombrestring
Nombre.
apellidostring
Apellido.
legajostring · puede ser null
Número de legajo. Llega null si el empleado no tiene legajo cargado.
nombreOrganizacionstring
Nombre de la organización en TuLegajo. Útil si un mismo sistema recibe eventos de varias organizaciones.
urlstring
Ruta relativa del recurso en la API de TuLegajo (base https://api.tulegajo.com). Permite consultar el detalle completo con tu API KEY, por ejemplo /empleados/20-12345678-9.

Los campos que no elijas no se envían. Un webhook puede no tener ningún campo del evento y solo campos fijos, aunque no es lo habitual.

Eventos disponibles

Estos son los eventos que hoy se pueden notificar. Algunos dependen de que tu organización tenga habilitado el módulo correspondiente (Licencias, Control horario).

Resumen

EventoSe dispara cuando…Módulo
Empleado creadose da de alta un empleadoBase
Empleado desvinculadose desvincula un empleadoBase
Empleado revinculadose revincula un empleado desvinculadoBase
Documento firmado por el empleadoun empleado firma un documento (conforme o no conforme)Base
Comunicación respondida por el empleadoun empleado responde una comunicación enviada por la empresaBase
Licencia aprobadauna licencia queda aprobadaLicencias
Licencia canceladauna licencia se cancelaLicencias
Fichada registradase registra una fichadaControl horario
EVENTO Empleado creado

Se dispara cada vez que se da de alta un empleado en la organización, sin importar el origen: interfaz web, importación masiva o la API.

Campos disponibles
cuil
CUIL.
nombre
Nombre.
apellido
Apellido.
legajo
Legajo.
nombreOrganizacion
Organización.
url
/empleados/{cuil}
EVENTO Empleado desvinculado

Se dispara cuando un empleado es desvinculado de la organización.

Campos disponibles
cuil
CUIL.
nombre
Nombre.
apellido
Apellido.
legajo
Legajo.
nombreOrganizacion
Organización.
url
/empleados/{cuil}
EVENTO Empleado revinculado

Se dispara cuando un empleado desvinculado vuelve a vincularse a la organización.

Campos disponibles
cuil
CUIL.
nombre
Nombre.
apellido
Apellido.
legajo
Legajo.
nombreOrganizacion
Organización.
url
/empleados/{cuil}
EVENTO Documento firmado por el empleado

Se dispara cuando el empleado firma un documento de un lote (por ejemplo, un recibo de sueldo), tanto si lo firma conforme como no conforme.

Campos disponibles
cuil
CUIL.
nombre
Nombre.
apellido
Apellido.
legajo
Legajo.
nombreOrganizacion
Organización.
conformeboolean
true si firmó conforme, false si firmó no conforme.
nombreLotestring
Nombre del lote al que pertenece el documento.
periodoLotestring · MM-AAAA
Período del lote, en el mismo formato que en la API (p. ej. 09-2026).
nombreArchivostring
Nombre del archivo cargado en el lote del que salió el documento.
url
/documentos/{id}
EVENTO Comunicación respondida por el empleado

Se dispara cuando un empleado responde (firma aceptando o rechazando) una comunicación que le envió la empresa.

Campos disponibles
cuil
CUIL.
nombre
Nombre.
apellido
Apellido.
legajo
Legajo.
nombreOrganizacion
Organización.
asuntostring
Asunto de la comunicación.
aceptadaboolean
true si el empleado la aceptó, false si la rechazó.
url
/empleados/comunicaciones/{id}
EVENTO Licencia aprobada

Se dispara cuando una solicitud de licencia queda aprobada (completa su circuito de aprobación) o cuando un responsable otorga una licencia directamente.

Campos disponibles
cuil
CUIL.
nombre
Nombre.
apellido
Apellido.
legajo
Legajo.
nombreOrganizacion
Organización.
tipoLicenciastring
Nombre del tipo de licencia (p. ej. Vacaciones).
fechaIniciostring · dd/MM/aaaa
Fecha de inicio.
fechaFinstring · dd/MM/aaaa
Fecha de fin.
diasnumber
Cantidad de días de la licencia.
url
/licencias/{id}
EVENTO Licencia cancelada

Se dispara cuando se cancela una licencia, ya sea porque un responsable la canceló o porque se aprobó el pedido de cancelación del empleado. Admite los mismos campos que Licencia aprobada.

Campos disponibles
cuil
CUIL.
nombre
Nombre.
apellido
Apellido.
legajo
Legajo.
nombreOrganizacion
Organización.
tipoLicenciastring
Nombre del tipo de licencia.
fechaIniciostring · dd/MM/aaaa
Fecha de inicio.
fechaFinstring · dd/MM/aaaa
Fecha de fin.
diasnumber
Cantidad de días de la licencia.
url
/licencias/{id}
EVENTO Fichada registrada

Se dispara por cada fichada que se registra en Control horario: desde la web, la app móvil, un dispositivo, la API, una carga manual o una importación. Si se cargan varias fichadas juntas, llega un envío por cada una.

Campos disponibles
cuil
CUIL.
nombre
Nombre.
apellido
Apellido.
legajo
Legajo.
tipoFichadastring
IN (entrada), OUT (salida) o UNKNOWN (sin tipo definido).
fechaHoranumber
Fecha y hora de la fichada como timestamp en milisegundos (epoch, UTC). Ej.: 1793262720000.
enTiempoRealboolean
true si el empleado fichó en el momento (web, app móvil o dispositivo); false si fue cargada a posteriori (manual o importación).
codigoDispositivostring · puede ser null
Código del dispositivo de fichada, o null si no se fichó desde un dispositivo.
Diferencia con los demás eventos

Este evento no admite nombreOrganizacion ni url.

Campos fijos

Además de los datos del evento, cada webhook puede incluir pares clave / valor fijos que se agregan tal cual a cada envío. Se usan para identificar el origen, el tipo de evento o para autenticar la solicitud.

Ejemplo de campos fijos
{
  "origen": "tulegajo",
  "evento": "documento_firmado",
  "token": "<un secreto que valida tu sistema>"
}
Los nombres no deben repetirse. Si un campo fijo tiene el mismo nombre que un campo del evento, prevalece el valor fijo. Los valores fijos siempre se envían como texto.

Seguridad

Como no se pueden agregar headers propios, recomendamos estas prácticas para asegurarte de que la solicitud viene de TuLegajo:

HTTPS
Usá siempre una URL https:// con un certificado válido. Así los datos personales del empleado y el token viajan cifrados.
Token en el cuerpo
Definí un campo fijo con un secreto (por ejemplo "token") y rechazá con 401 cualquier solicitud que no lo traiga o no coincida.
Token en la URL
Alternativa: incluí el secreto en la propia URL configurada, p. ej. https://erp.ejemplo.com/hooks?key=….
Datos a confirmar
Si tu proceso es sensible, usá el campo url para consultar el recurso en la API de TuLegajo con tu API KEY antes de actuar.

Si necesitás cambiar el secreto, pedínoslo por soporte (ver Cambios y bajas).

Entregas y reintentos

Los envíos se procesan en una cola, de forma asíncrona e independiente de la operación que los originó.

AspectoComportamiento
Respuesta exitosaCualquier código 2xx. El cuerpo de la respuesta se ignora.
Tiempo de espera30 segundos. Si tu sistema tarda más, el envío se considera fallido.
ReintentosAnte un 4xx, 5xx, timeout o error de conexión, el envío se reintenta, con algunos minutos de espera entre intentos, hasta 3 intentos en total. Después se descarta.
RedireccionesLa URL configurada no debe redirigir. Ante un 301 o 302 la solicitud llega a destino sin el cuerpo, es decir, sin los datos del evento. Configurá la URL final, incluido https:// y la barra final si tu servidor la exige.
OrdenNo garantizado. Dos eventos muy cercanos pueden llegar en otro orden.
DuplicadosPosibles. Si tu sistema procesó el mensaje pero no respondió a tiempo, el mismo evento puede llegar de nuevo.

Recomendaciones para tu endpoint

  • Respondé rápido

    Guardá el mensaje y devolvé 200; hacé el procesamiento pesado después.

  • Procesá de forma idempotente

    Que recibir dos veces el mismo mensaje no genere efectos dobles (por ejemplo, identificá la fichada por CUIL + hora).

  • Respondé 4xx solo si reintentar no sirve

    Un 4xx también se reintenta; si el mensaje es inválido, registralo y respondé 200 para no recibirlo otra vez.

  • Tolerá campos nuevos

    No rechaces el mensaje si trae atributos que no esperás.

Información requerida

Para configurar tus webhooks necesitamos los siguientes datos. Envialos al equipo de soporte de TuLegajo; podés usar la plantilla de abajo.

Datos generales

  • Organización

    Nombre de la organización en TuLegajo (y CUIT) donde se configuran los webhooks.

  • Ambiente

    Producción u homologación. Si querés probar primero, pedilo en homologación con una URL de pruebas.

  • Contacto técnico

    Nombre y correo de quien recibe avisos si los envíos empiezan a fallar.

Por cada webhook

WEBHOOK Un evento → una URL
Datos a enviarnos
Evento Requerido
Uno de los eventos disponibles, p. ej. Documento firmado por el empleado.
URL de destino Requeridohttps://…
URL completa, accesible desde Internet, donde tu sistema recibe el envío, sin redirecciones (ver Entregas y reintentos). Puede incluir query string.
Método HTTP RequeridoPOST · PUT · PATCH · DELETE
Recomendamos POST. En todos los casos los datos viajan como JSON en el cuerpo (ver Formato del envío).
Campos y sus nombres Requeridocampo [→ otro nombre]
Qué campos del evento querés recibir. Llegan con el nombre documentado; si tu sistema espera otro, indicá el reemplazo, p. ej. legajo → nroLegajo. Solo se aceptan campos que el evento admite.
Campos fijos Opcionalclave → valor
Valores constantes a incluir en cada envío, p. ej. un token o el nombre del evento (ver Campos fijos). Si incluye secretos, envialos por un canal seguro.

Plantilla

SOLICITUD DE CONFIGURACIÓN DE WEBHOOKS — TuLegajo

Organización:        <nombre en TuLegajo> (CUIT <...>)
Ambiente:            <Producción | Homologación>
Contacto técnico:    <nombre> <correo>

--- Webhook 1 ---
Evento:              <nombre del evento>
URL de destino:      <https://...>
Método HTTP:         <POST | PUT | PATCH | DELETE>
Campos a recibir (y otro nombre, solo si lo necesitás):
  <campo>
  <campo>          -> <otro nombre>
Campos fijos (opcional):
  <clave>          = <valor>

--- Webhook 2 ---
...

Ejemplo completo

Un cliente quiere enterarse en su ERP de cada recibo firmado, y saber si fue conforme.

1 · Lo que nos envía
Organización:        Ejemplo S.A. (CUIT 30-12345678-9)
Ambiente:            Producción
Contacto técnico:    Mesa de integraciones <[email protected]>

--- Webhook 1 ---
Evento:              Documento firmado por el empleado
URL de destino:      https://erp.ejemplo.com/webhooks/tulegajo
Método HTTP:         POST
Campos a recibir:
  cuil
  legajo
  conforme
  nombreLote     -> lote
  periodoLote    -> periodo
  url            -> recurso
Campos fijos:
  evento         = recibo_firmado
  token          = <secreto compartido>
2 · Lo que recibe su ERP cuando un empleado firma
POST /webhooks/tulegajo HTTP/1.1
Host: erp.ejemplo.com
Content-Type: application/json

{
  "cuil": "20-12345678-9",
  "legajo": "1234",
  "conforme": false,
  "lote": "Recibos de sueldo",
  "periodo": "09-2026",
  "recurso": "/documentos/48213",
  "evento": "recibo_firmado",
  "token": "<secreto compartido>"
}
3 · (Opcional) Consulta del detalle en la API
GET https://api.tulegajo.com/documentos/48213
x-api-key: <tu API KEY>
User-Agent: api-consumer

El orden de los atributos en el JSON no está garantizado.

Cambios y bajas

Cualquier cambio sobre un webhook ya configurado se pide al equipo de soporte, indicando organización, evento y URL actual.

PedidoQué pasa
ModificarSe puede cambiar la URL, el método, los campos y sus nombres, o los campos fijos (por ejemplo, rotar el token).
PausarEl webhook se desactiva: los eventos que ocurran mientras esté pausado no se envían ni se acumulan.
ReactivarVuelve a enviar los eventos que ocurran desde ese momento.
EliminarSe borra la configuración. Si la organización se da de baja en TuLegajo, sus webhooks se eliminan automáticamente.
No hay reenvío de eventos pasados. Si tu sistema estuvo caído más allá de los reintentos, usá la API de TuLegajo para reconciliar (por ejemplo, listando documentos o licencias por fecha).

Historial de versiones

FechaVersiónComentario
29/10/20261.0.0Versión inicial: eventos de empleados, documentos, comunicaciones, licencias y control horario; formato del envío, reintentos e información requerida para la configuración.