Webhooks

Aplica a: NominaHQ Roles: Acceso total y Administrador (crear, editar y eliminar suscripciones); todos los roles del personal pueden ver la página. Referencias regulatorias: ninguna

Resumen

Los Webhooks permiten que NominaHQ avise a sus propios sistemas cada vez que ocurre un evento de planilla (por ejemplo, una planilla aprobada, pagada o contabilizada, o un Décimo contabilizado). NominaHQ envía una solicitud HTTP POST con los datos del evento a la URL que usted registre, firmada con HMAC-SHA256 para que su sistema pueda verificar el origen. La página también recibe webhooks de sistemas externos (Bancos, relojes de marcación) y muestra una bitácora de cada intento de entrega. Esta función la usa el personal técnico del proveedor que integra NominaHQ con otros sistemas.

Navegación

Menú lateral: Configuración → Webhooks (ruta /settings/webhooks).

Las suscripciones y entregas son por empresa (cliente): la página muestra siempre las del cliente activo seleccionado.

Conceptos clave

• Webhook saliente (suscripción): una URL suya a la que NominaHQ envía notificaciones cuando ocurre un evento suscrito.
• Evento: la acción de negocio que dispara el envío. Cada evento tiene una clave (por ejemplo payroll.run.posted).
• HMAC-SHA256: firma criptográfica del cuerpo del mensaje calculada con el secreto compartido. Viaja en el encabezado X-NominaHQ-Signature y permite a su sistema confirmar que el mensaje proviene de NominaHQ y no fue alterado.
• Webhook entrante: un mensaje que un sistema externo envía a NominaHQ en /api/v1/webhooks/{source}. NominaHQ guarda el cuerpo para procesarlo y auditarlo.
• Registro de entregas (deliveries): la bitácora de cada intento de envío saliente, con el código HTTP de respuesta, la duración y el error, si lo hubo.
• Protección contra SSRF: control de seguridad que impide que NominaHQ envíe webhooks a direcciones internas o privadas.

Tarea 1 — Crear un webhook saliente

Antes de empezar: necesita el rol Acceso total. Seleccione en la barra superior la empresa cuyos eventos quiere recibir: los webhooks son por empresa. Tenga lista la URL https:// de su sistema receptor.

1. En el menú lateral, dentro de Configuración, haga clic en Webhooks.

   

   Arriba están las suscripciones de la empresa activa (en el ejemplo, todavía ninguna: "Aún no hay webhooks"); más abajo, Entregas recientes.

2. Haga clic en Nuevo.

   

   Se abre el cuadro Nuevo Webhook.

3. En Nombre, escriba un nombre que identifique al sistema receptor (en el ejemplo, Portal RRHH (demo)).

   

   El nombre no se puede cambiar después de guardar.

4. En URL, escriba la dirección de su sistema que recibirá los eventos.

   

   Debe ser una dirección pública https:// (o http://); NominaHQ no envía a direcciones internas.

5. En Secreto (HMAC), escriba un secreto de firma y compártalo con quien programa el sistema receptor.

   

   Es opcional, pero sin secreto los mensajes no llevan firma y su sistema no puede comprobar que vienen de NominaHQ.

6. En Eventos, deje * para recibir todos, o escriba las claves separadas por comas (por ejemplo payroll.run.paid,payslips.issued).

   

   Las claves disponibles están en la tabla Eventos salientes disponibles más abajo.

7. Deje marcada la casilla Activo y haga clic en Guardar.

   

   Guardar se habilita cuando Nombre y URL tienen valor.

8. Revise la lista: aparece el aviso "Webhook guardado" y la nueva suscripción con su URL y sus eventos.

   

   Para cambiar la URL, el secreto, los eventos o Activo, haga clic en el nombre. Al editar, el secreto aparece vacío: déjelo así para conservarlo o escriba uno nuevo para reemplazarlo.

Resultado: cada vez que ocurra uno de los eventos suscritos en esa empresa, NominaHQ envía un POST con los datos del evento a su URL.

Tarea 2 — Revisar las entregas

9. Baje hasta Entregas recientes. Cada fila es un intento de envío, del más reciente al más antiguo. El historial se conserva aunque la suscripción que lo generó ya se haya eliminado.

   

   En el ejemplo, OK sin marcar y HTTP 405: el sistema receptor rechazó el mensaje. Revise la columna Error y el registro de su sistema.

Resultado: usted sabe si su sistema recibió cada evento. Use el botón con la flecha circular, junto a Nuevo, para recargar las tablas.

Tarea 3 — Eliminar un webhook

10. En la lista de suscripciones, haga clic derecho sobre la fila y elija Eliminar.

    

    Si solo quiere pausar los envíos, edite la suscripción y desmarque Activo.

11. En el cuadro Eliminar, confirme con Confirmar.

    

    Con Cancelar se cierra sin eliminar.

Resultado: aparece "Webhook eliminado" y la suscripción deja de recibir envíos.

Verificar la firma en su sistema

1. Lea el encabezado X-NominaHQ-Signature; su valor tiene el formato sha256=<hexadecimal>.
2. Calcule el HMAC-SHA256 del cuerpo exacto recibido usando el mismo Secreto (HMAC) y compárelo con el valor del encabezado.
3. El encabezado X-NominaHQ-Event indica la clave del evento. El tipo de contenido es application/json.

Referencia de campos

Cuadro Nuevo Webhook / Editar Webhook

El botón Guardar permanece deshabilitado mientras Nombre o URL estén vacíos.

Tabla de suscripciones

Tabla Entregas recientes

Eventos salientes disponibles

Formato del mensaje saliente

El cuerpo es JSON con esta estructura:

{
  "event": "payroll.run.posted",
  "sentAt": "fecha y hora UTC",
  "data": {
    "runId": "…",
    "runType": "…",
    "periodStart": "…",
    "periodEnd": "…",
    "payDate": "…",
    "status": "…",
    "entryCount": 0,
    "totalGross": 0,
    "totalNet": 0
  }
}

Encabezados incluidos en cada envío:

Webhooks entrantes

NominaHQ acepta mensajes de sistemas externos por HTTP POST en /api/v1/webhooks/{source}, donde {source} identifica al remitente (por ejemplo un banco o un reloj de marcación). El cuerpo de la solicitud se guarda sin cambios para su procesamiento y auditoría. El encabezado opcional X-Event-Type se registra como tipo de evento. Se conserva también la dirección IP de origen y la fecha y hora de recepción. La respuesta confirma la recepción.

Estos mensajes no aparecen en las tablas de la página de Webhooks; se almacenan internamente para procesamiento posterior.

Seguridad

• Solo HTTP/HTTPS: las URL de destino deben usar http o https.
• Protección contra SSRF: NominaHQ rechaza enviar a direcciones no públicas: bucle local (loopback), redes privadas (10.x, 172.16–31.x, 192.168.x), CGNAT (100.64.x), enlace local incluida la dirección de metadatos de nube 169.254.169.254, multidifusión y reservadas, y sus equivalentes IPv6. La verificación se hace contra la dirección IP real a la que se conecta, por lo que no puede evadirse cambiando el DNS.
• Sin redirecciones automáticas: una respuesta de redirección (30x) no puede desviar el envío a un destino interno.
• Tiempo de espera de conexión: 8 segundos.
• Aislamiento: una falla de entrega de webhook nunca interrumpe la operación de planilla; el intento simplemente se registra como fallido.

Roles y permisos

La gestión de webhooks es una tarea de configuración del sistema; solo el rol Acceso total y los Administradores pueden crear, editar o eliminar suscripciones. Todos los roles del personal pueden ver la página.

Solución de problemas

Funciones relacionadas

• Integración (Configuración → Integración) — Contabilización en CifraHQ.
• API REST — claves de API y documentación de la API.
• Auditoría — historial de cambios del sistema.