API pública y webhooks

Workfide expone una API REST nativa para conectar el registro de jornada verificable con tu ERP, nómina, BI o herramientas internas. Las claves se generan desde Ajustes → API pública y webhooks y pertenecen a una única organización.

Autenticación

Envía la clave en la cabecera Authorization. Solo se almacena su hash: si la pierdes, revócala y crea otra.

Cabeceras

Authorization: Bearer wf_<prefijo>_<secreto>
Content-Type: application/json

Endpoints

GET/api/public/v1/employeesscope: read

Plantilla y contratos activos de la organización.

GET/api/public/v1/evidence?from=&to=&employee_id=&limit=scope: read

Eventos del registro append-only con su hash encadenado.

POST/api/public/v1/clockscope: write

Registra clock_in, clock_out, break_start o break_end.

Ejemplo: registrar un fichaje

curl -X POST https://workfide.com/api/public/v1/clock \
  -H "Authorization: Bearer wf_xxxxxxxxxxxx_yyyy" \
  -H "Content-Type: application/json" \
  -d '{"employee_id":"<uuid>","event_type":"clock_in"}'

Webhooks firmados

Registra una URL HTTPS y Workfide enviará cada evento de jornada con firma HMAC-SHA256 del cuerpo en x-workfide-signature. Reintentos automáticos hasta 5 veces.

Payload

POST https://erp.miempresa.com/workfide
x-workfide-event: clock_in
x-workfide-signature: <hmac_sha256_hex>

{
  "event": "clock_in",
  "event_id": "…",
  "seq": 1042,
  "organization_id": "…",
  "employee_id": "…",
  "occurred_at": "2026-01-15T08:02:11.000Z",
  "hash": "…"
}

Verificación de la firma (Node)

import { createHmac, timingSafeEqual } from "node:crypto";

const expected = createHmac("sha256", SIGNING_SECRET).update(rawBody).digest("hex");
const ok = timingSafeEqual(Buffer.from(expected), Buffer.from(signature));

Seguridad

• Claves con ámbito por organización y revocación inmediata.
• Scopes separados de lectura y escritura.
• Todos los fichajes creados vía API quedan marcados como origen `public_api`.
• El registro sigue siendo append-only: la API no puede editar ni borrar evidencia.