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.
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
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
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
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
Tu sistema responde 2xx
Cualquier respuesta 2xx en menos de 30 segundos da la entrega por exitosa. Si no, reintentamos (ver Entregas y reintentos).
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 configurado | Dónde viajan los datos | Notas |
|---|---|---|
POSTPUTPATCHDELETE | Cuerpo JSON | Objeto plano (sin anidar) con un atributo por cada campo elegido. Recomendamos POST. |
Headers enviados
| Header | Valor |
|---|---|
Content-Type | application/json |
No es posible agregar headers personalizados (por ejemplo Authorization). Para autenticar los envíos, ver Seguridad.
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"
}
"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
/empleados/{cuil}).null si el empleado no tiene legajo cargado.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
| Evento | Se dispara cuando… | Módulo |
|---|---|---|
| Empleado creado | se da de alta un empleado | Base |
| Empleado desvinculado | se desvincula un empleado | Base |
| Empleado revinculado | se revincula un empleado desvinculado | Base |
| Documento firmado por el empleado | un empleado firma un documento (conforme o no conforme) | Base |
| Comunicación respondida por el empleado | un empleado responde una comunicación enviada por la empresa | Base |
| Licencia aprobada | una licencia queda aprobada | Licencias |
| Licencia cancelada | una licencia se cancela | Licencias |
| Fichada registrada | se registra una fichada | Control horario |
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.
/empleados/{cuil}Se dispara cuando un empleado es desvinculado de la organización.
/empleados/{cuil}Se dispara cuando un empleado desvinculado vuelve a vincularse a la organización.
/empleados/{cuil}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.
true si firmó conforme, false si firmó no conforme.09-2026)./documentos/{id}Se dispara cuando un empleado responde (firma aceptando o rechazando) una comunicación que le envió la empresa.
true si el empleado la aceptó, false si la rechazó./empleados/comunicaciones/{id}Se dispara cuando una solicitud de licencia queda aprobada (completa su circuito de aprobación) o cuando un responsable otorga una licencia directamente.
Vacaciones)./licencias/{id}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.
/licencias/{id}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.
IN (entrada), OUT (salida) o UNKNOWN (sin tipo definido).1793262720000.true si el empleado fichó en el momento (web, app móvil o dispositivo); false si fue cargada a posteriori (manual o importación).null si no se fichó desde un dispositivo.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>"
}
Seguridad
Como no se pueden agregar headers propios, recomendamos estas prácticas para asegurarte de que la solicitud viene de TuLegajo:
https:// con un certificado válido. Así los datos personales del empleado y el token viajan cifrados."token") y rechazá con 401 cualquier solicitud que no lo traiga o no coincida.https://erp.ejemplo.com/hooks?key=….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ó.
| Aspecto | Comportamiento |
|---|---|
| Respuesta exitosa | Cualquier código 2xx. El cuerpo de la respuesta se ignora. |
| Tiempo de espera | 30 segundos. Si tu sistema tarda más, el envío se considera fallido. |
| Reintentos | Ante 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. |
| Redirecciones | La 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. |
| Orden | No garantizado. Dos eventos muy cercanos pueden llegar en otro orden. |
| Duplicados | Posibles. Si tu sistema procesó el mensaje pero no respondió a tiempo, el mismo evento puede llegar de nuevo. |
Recomendaciones para tu endpoint
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
Por cada webhook
POST. En todos los casos los datos viajan como JSON en el cuerpo (ver Formato del envío).legajo → nroLegajo. Solo se aceptan campos que el evento admite.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íaOrganizació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.
| Pedido | Qué pasa |
|---|---|
| Modificar | Se puede cambiar la URL, el método, los campos y sus nombres, o los campos fijos (por ejemplo, rotar el token). |
| Pausar | El webhook se desactiva: los eventos que ocurran mientras esté pausado no se envían ni se acumulan. |
| Reactivar | Vuelve a enviar los eventos que ocurran desde ese momento. |
| Eliminar | Se borra la configuración. Si la organización se da de baja en TuLegajo, sus webhooks se eliminan automáticamente. |
Historial de versiones
| Fecha | Versión | Comentario |
|---|---|---|
| 29/10/2026 | 1.0.0 | Versión inicial: eventos de empleados, documentos, comunicaciones, licencias y control horario; formato del envío, reintentos e información requerida para la configuración. |