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.

Paso a paso

Crear una suscripción saliente

1. Vaya a Configuración > Webhooks.
2. Presione Nuevo.
3. Nombre (Name): escriba un nombre que identifique la suscripción. Obligatorio. No se puede cambiar después de creada.
4. URL: escriba la dirección https:// de su sistema que recibirá los eventos. Obligatorio.
5. Secret (HMAC): escriba un secreto de firma. Opcional. Si lo deja en blanco, los mensajes se envían sin firma.
6. Events: escriba * para recibir todos los eventos, o una lista de claves separadas por comas (por ejemplo payroll.run.posted,decimo.posted). Opcional; si lo deja vacío equivale a *.
7. Activo (Active): deje marcada la casilla para que la suscripción reciba envíos. Opcional.
8. Presione Guardar. Aparece el mensaje Webhook saved.

Editar o eliminar una suscripción

1. Haga clic en el nombre de la suscripción en la tabla, o use el menú contextual (clic derecho) y elija view/edit.
2. Modifique la URL, el Secret (HMAC), los Events o el estado Activo. El campo Nombre aparece bloqueado al editar.
   • El campo Secret (HMAC) aparece vacío al editar. Si lo deja en blanco, se conserva el secreto anterior; escriba un valor nuevo solo si desea reemplazarlo.
3. Presione Guardar.
4. Para eliminar, use el menú contextual y elija delete; confirme en el cuadro de diálogo. Aparece el mensaje Webhook deleted.

Revisar las entregas

En la sección Recent deliveries se listan los intentos de envío más recientes (ordenados por fecha y hora, del más nuevo al más antiguo). Cada fila muestra hora (Time), evento (Event), éxito (OK), código HTTP (HTTP), duración en milisegundos (ms), la URL de destino y el Error, si lo hubo. Presione el botón de actualizar para recargar las tablas.

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 Secret (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

Diálogo Nuevo/Editar suscripción (New Webhook / Edit Webhook)

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

Tabla de suscripciones

Tabla Recent deliveries

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 Desarrolladores (Configuración > API Desarrolladores) — documentación de la API y verificación de firmas.
• Auditoría — historial de cambios del sistema.