Integración

Esta guía te acompaña paso a paso en la configuración de un webhook desde el dashboard de Sheriff, y explica cómo preparar tu servidor para recibir y validar las entregas de forma segura.

Paso 1: Acceder al panel de webhooks

1. Ingresa al dashboard web de Sheriff en app.thesheriff.pe.
2. En el menú de navegación, abre Integraciones → Webhooks.
3. Verás la lista de webhooks configurados (si es la primera vez, estará vacía).

Permisos necesarios

Solo los usuarios con rol Admin pueden crear, editar o desactivar webhooks. Los demás usuarios pueden visualizar la configuración e historial pero no modificarlos.

Paso 2: Crear un webhook

Haz clic en Crear webhook. Se abrirá un modal con el formulario de configuración.

Campos del formulario

Tipo de webhook

Selecciona el tipo de evento al que quieres suscribirte. Actualmente está disponible:

• Descarga Resumen de Perfil: se dispara cuando tu sistema llama al endpoint POST /v1/webhook/perfiles/resumen.

Hasta 3 configuraciones activas por tipo

Cada corporación puede tener hasta 3 configuraciones activas del mismo tipo de webhook al mismo tiempo. Cada configuración tiene su propia URL, headers, OAuth y secretKey. Cuando se dispare un evento, Sheriff enviará el payload a cada configuración activa en paralelo.

Nombre (opcional)

Etiqueta corta para identificar la configuración cuando tienes varias del mismo tipo (ej: "Producción", "BI", "Backup"). Aparece en el dashboard junto a cada configuración y en el detalle de auditoría de cada evento.

URL del webhook

La URL destino a la que Sheriff enviará el payload cuando se dispare el webhook. Es una sola URL por configuración. Si necesitas enviar a múltiples destinos, crea una configuración adicional para cada uno (hasta 3 activas por tipo).

Múltiples destinos

Útil cuando necesitas replicar el webhook a múltiples sistemas (por ejemplo tu ERP principal + un sistema secundario de BI o un ambiente de staging para pruebas). Crea una configuración por cada destino y desactiva la que no necesites.

Descripción

Texto libre para identificar internamente la configuración (ej: "Integración ERP producción"). Es solo para tu referencia, no se envía en los requests.

Headers personalizados

JSON con headers adicionales que Sheriff incluirá en cada request. Por ejemplo:

{
  "X-Environment": "production",
  "X-Custom-Key": "valor"
}

Estos headers se suman a los headers propios del webhook (Content-Type, X-Sheriff-Signature, etc.). Si el JSON es inválido, el formulario te lo marcará al guardar.

OAuth 2.0 (opcional)

Activa este toggle si tu servidor webhook requiere autenticación Bearer token. Sheriff usará el flujo client_credentials para obtener un token antes de cada entrega.

Campos a completar cuando está habilitado:

Campo	Descripción
Token URL	Endpoint de tu servidor de auth que emite tokens. Ej: https://auth.tu-dominio.com/oauth/token.
Client ID	Identificador del cliente OAuth que Sheriff usará.
Client Secret	Secret del cliente OAuth. Se almacena encriptado con AES-256-GCM en nuestra DB.
Grant Type	Siempre client_credentials.
Audience	Opcional. Según lo requiera tu servidor de auth.
Scope	Opcional. Según lo requiera tu servidor de auth.

Edición de Client Secret

Al editar un webhook existente, el campo Client Secret aparece vacío. Si lo dejas vacío, se mantiene el valor anterior. Si escribes un nuevo valor, reemplazará al actual.

Estado activo

Toggle para habilitar o deshabilitar la configuración. Solo las configuraciones activas reciben entregas. Si ninguna configuración del tipo está activa cuando disparas el webhook, el endpoint retorna un error 400 indicando que no hay webhook configurado.

Paso 3: Guardar la secretKey

Al crear cada configuración, la plataforma te mostrará un banner con la clave secreta (secretKey) que Sheriff usará para firmar los mensajes enviados a esa URL.

Una secretKey por configuración

Cada configuración tiene su propia secretKey. Si tienes 3 configuraciones activas del mismo tipo, recibirás 3 claves distintas (una por cada URL). Tu servidor debe usar la secretKey correcta según la URL destino que esté validando.

Esta clave se muestra una sola vez

Cópiala y guárdala en un lugar seguro (variable de entorno, secrets manager). Si la pierdes, tendrás que recrear la configuración para obtener una nueva.

Esta clave es la que usarás del lado de tu servidor para verificar que cada webhook recibido realmente viene de Sheriff.

Paso 4: Preparar tu servidor

Tu servidor debe estar preparado para:

1. Recibir requests POST con un body JSON en las URLs que configuraste.
2. Verificar la firma HMAC del header X-Sheriff-Signature.
3. (Opcional) Aceptar el Bearer token de OAuth si lo habilitaste.
4. Responder con un código HTTP 2xx dentro de 30 segundos para que la entrega se considere exitosa.

Revisa la Vista General para conocer la estructura exacta del payload y los headers que recibirás.

Tiempo de entrega

Cuando dispares el webhook con un perfil que aún no está cargado en tu cuenta, la entrega puede demorar un par de segundos (mientras Sheriff consulta SUNAT, Sentinel, REDJUM, etc.). Si el perfil ya está activo, la entrega es casi inmediata. Diseña tu servidor receptor para tolerar esta variabilidad.

Seguridad

La seguridad se apoya en dos mecanismos independientes que operan en direcciones opuestas.

1. Verificación de firma HMAC (siempre requerida)

Sheriff firma el body del mensaje con tu secretKey usando HMAC-SHA256 y envía la firma en el header X-Sheriff-Signature. Debes recalcular la firma en tu servidor y compararla para garantizar que el mensaje realmente viene de Sheriff.

Valida siempre la firma

Sin esta verificación, cualquiera que descubra tu URL podría enviarte datos falsos. La verificación de la firma es la única forma de garantizar autenticidad.

Ejemplo de verificación en Node.js:

const crypto = require("crypto");

function verifySheriffSignature(rawBody, signatureHeader, secretKey) {
  const expected =
    "sha256=" +
    crypto.createHmac("sha256", secretKey).update(rawBody).digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signatureHeader),
  );
}

// En tu handler Express:
app.post(
  "/webhooks/sheriff",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const signature = req.headers["x-sheriff-signature"];
    const isValid = verifySheriffSignature(
      req.body,
      signature,
      process.env.SHERIFF_WEBHOOK_SECRET,
    );

    if (!isValid) {
      return res.status(401).send("Invalid signature");
    }

    const payload = JSON.parse(req.body.toString());
    // ... procesa el webhook
    res.status(200).send("OK");
  },
);

Ejemplo en Python:

import hmac
import hashlib

def verify_sheriff_signature(raw_body: bytes, signature_header: str, secret_key: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret_key.encode("utf-8"),
        raw_body,
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(expected, signature_header)

Usa el raw body

La firma se calcula sobre el body exacto que envía Sheriff. Si tu framework parsea el JSON antes de que puedas inspeccionar los bytes originales (por ejemplo, con express.json()), la firma no coincidirá. Usa el raw body (express.raw() o equivalente) solo para esta verificación.

2. OAuth 2.0 (opcional)

Si tu servidor webhook está protegido detrás de autenticación (por ejemplo, requiere un token Bearer válido para aceptar requests), activa OAuth 2.0 en la configuración del webhook.

Sheriff obtendrá un access_token desde tu servidor de autenticación antes de cada entrega y lo incluirá en el header Authorization. El Client Secret se almacena encriptado con AES-256-GCM en nuestra base de datos y solo se desencripta en memoria al momento de solicitar el token.

Defensa en profundidad

La verificación HMAC y OAuth 2.0 son mecanismos complementarios. HMAC valida que el mensaje no fue alterado y proviene de Sheriff. OAuth valida que quien llama a tu endpoint está autorizado. Tener ambos es una buena práctica de seguridad.