Recibir webhooks

Clausum notifica a tus sistemas resultados de assess, fraude, expedientes y disputas mediante solicitudes HTTP POST firmadas. Consulta Eventos webhook para el catálogo completo de 15 eventos.

1. Registrar un endpoint

Panel (recomendado)

Abre Conexiones → pestaña Empezar → sección Webhooks salientes (sandbox o producción).
Ingresa URL HTTPS y selecciona eventos (los 15 tipos disponibles).
Copia el secreto de firma mostrado una sola vez al crear.

Nota de producción: crear un webhook de producción puede requerir credenciales live aprobadas para tu organización. Los webhooks sandbox funcionan de inmediato con claves clm_*_sbx_*. API (opcional): GET/POST /api/v1/integrations/merchant-webhooks con JWT de sesión del panel — misma lista de eventos que la UI.

2. Sandbox vs producción

Entorno	Claves API	Entregas webhook
Sandbox	`clm_sk_sbx_` / `clm_pub_sbx_`	URLs + secretos separados por entorno
Producción	`clm_sk_` / `clm_pub_`	URLs + secretos separados

Assess con claves sandbox dispara solo webhooks sandbox.

3. Entender la entrega

Encabezado	Ejemplo	Descripción
`X-Clausum-Signature`	`t=1716998400,v1=8a9b...`	Firma HMAC
`X-Clausum-Event`	`transaction.created`	Tipo de evento
`X-Clausum-Timestamp`	`2026-07-05T18:30:00Z`	Hora de entrega

Cuerpo:

{
  "event": "transaction.created",
  "timestamp": "2026-07-05T18:30:00.000Z",
  "data": {
    "session_id": "ps_...",
    "decision": "approve",
    "assess_response": { "decision": "approve", "session_id": "ps_..." }
  }
}

4. Verificar la firma

HMAC_SHA256(secret, "<timestamp>.<rawBody>") → encabezado t=...,v1=<hex>. Verifica el cuerpo raw antes de parsear JSON.

import crypto from "crypto"

export function verifyClausumSignature(rawBody: string, header: string, secret: string): boolean {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")))
  const timestamp = parts["t"]
  const provided = parts["v1"]
  if (!timestamp || !provided) return false

  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex")

  return crypto.timingSafeEqual(Buffer.from(provided), Buffer.from(expected))
}

import hmac, hashlib

def verify_clausum_signature(raw_body: str, header: str, secret: str) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    timestamp, provided = parts.get("t"), parts.get("v1")
    if not timestamp or not provided:
        return False
    expected = hmac.new(
        secret.encode(),
        f"{timestamp}.{raw_body}".encode(),
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(provided, expected)

5. Manejar el evento

export async function POST(req: Request) {
  const raw = await req.text()
  const signature = req.headers.get("x-clausum-signature")

  if (!signature || !verifyClausumSignature(raw, signature, process.env.CLAUSUM_WEBHOOK_SECRET!)) {
    return new Response("Invalid signature", { status: 401 })
  }

  const event = JSON.parse(raw)

  switch (event.event) {
    case "transaction.created":
    case "transaction.blocked":
      await syncOrderFromAssess(event.data)
      break
    case "fraud.detected":
      await onFraudDetected(event.data)
      break
    case "dispute.created":
      await onDispute(event.data)
      break
  }

  return new Response("ok", { status: 200 })
}

Monitorear entregas

Conexiones → Monitor → Entregas de webhooks salientes muestra intentos recientes, estado HTTP y estado de reintento.

Buenas prácticas

Verificar contra el cuerpo raw

Lee el texto raw primero, verifica, luego parsea JSON.

Responder rápido

Devuelve 2xx en pocos segundos; usa una cola para trabajo pesado.

Ser idempotente

Hay duplicados — clave por session_id + event o case_id.

Suscribirse de forma acotada

Empieza con transaction.blocked, transaction.created y fraud.detected; agrega eventos de disputa cuando tu flujo de chargeback esté listo.

Primeros pasos

Integración por tipo de cliente

Soluciones y prevención

Capacidades — eventos y operaciones

Panel de control

Conceptos clave

Referencia

Recibir webhooks

1. Registrar un endpoint

2. Sandbox vs producción

3. Entender la entrega

4. Verificar la firma

5. Manejar el evento

Monitorear entregas

Buenas prácticas

​1. Registrar un endpoint

​2. Sandbox vs producción

​3. Entender la entrega

​4. Verificar la firma

​5. Manejar el evento

​Monitorear entregas

​Buenas prácticas

1. Registrar un endpoint

2. Sandbox vs producción

3. Entender la entrega

4. Verificar la firma

5. Manejar el evento

Monitorear entregas

Buenas prácticas