Eventos webhook

Clausum envía webhooks salientes a endpoints HTTPS que configures en Conexiones → Empezar → Webhooks salientes (sandbox y producción son independientes). Cada entrega es un POST HTTP con cuerpo JSON y headers de firma HMAC. Consulta Recibir webhooks para verificación y manejo.

Catálogo de eventos (16 eventos)

Evento	Cuándo se dispara
`transaction.created`	Tras `POST /api/v1/assess` (o payout assess) devuelve `approve`, `review` o `challenge`
`transaction.blocked`	Tras assess devuelve `decline`
`assess.outcome_applied`	Tras `POST /api/v1/assess/outcome` o cierre automatizado de disputa (chargeback ganado/perdido, etc.)
`case.recommended`	Tras assess en vivo cuando el tier de riesgo amerita expediente (incluye `wizard_url`, `tier`, `risk_score`)
`transaction.succeeded`	Proveedor de pago entrante confirma éxito (vía ingest genérico o adaptador nativo opcional)
`transaction.failed`	Proveedor entrante reporta fallo de pago
`fraud.detected`	Fraude reportado vía `POST /api/v1/report-fraud` o flujo equivalente
`fraud.confirmed`	Expediente marcado como fraude confirmado en el panel
`case.created`	Expediente abierto automáticamente (p. ej. disputa / alerta temprana vía ingest)
`case.updated`	Estado o campos del expediente cambiaron
`case.dispatched`	Expediente enviado a participantes (email + anexo forense)
`case.authority_response`	Autoridad institucional actualizó seguimiento del expediente
`case.dispatch_acknowledged`	Participante acusó recibo del envío
`dispute.created`	Chargeback / disputa abierta
`dispute.updated`	Disputa actualizada mientras está abierta
`dispute.resolved`	Disputa cerrada (ganada, perdida o retirada)

Suscríbete solo a eventos que tu backend manejará — la lista de checkboxes del panel coincide exactamente con este catálogo.

Ejemplos de payload

`transaction.created` (assess approve / review / challenge)

{
  "event": "transaction.created",
  "timestamp": "2026-07-05T18:30:00.000Z",
  "data": {
    "session_id": "ps_1716998400000_abc",
    "decision": "approve",
    "risk_score": 12,
    "order_id": "ORD-2024-991",
    "payment_id": "pi_3Nxyz",
    "amount": 4500,
    "currency": "USD",
    "email": "buyer@example.com",
    "flow": "payin",
    "assess_response": {
      "decision": "approve",
      "session_id": "ps_1716998400000_abc",
      "risk_score": 12,
      "signals": []
    }
  }
}

`case.recommended`

{
  "event": "case.recommended",
  "timestamp": "2026-09-12T01:00:00.000Z",
  "data": {
    "session_id": "ps_1716998400000_abc",
    "payment_session_id": "uuid",
    "decision": "approve",
    "tier": "critical",
    "action": "auto_send",
    "risk_score": 82,
    "approved_but_suspicious": true,
    "suggested_submit_mode": "auto_send",
    "wizard_url": "https://dashboard.clausum.ai/dashboard/cases/nuevo?from=transaction&…",
    "case_id": null,
    "auto_created": false
  }
}

`assess.outcome_applied`

{
  "event": "assess.outcome_applied",
  "timestamp": "2026-08-02T12:00:00.000Z",
  "data": {
    "session_id": "ps_1716998400000_abc",
    "outcome": "chargeback_lost",
    "outcome_id": "uuid",
    "feedback_applied": true,
    "feedback": { "blocklist": true },
    "provider": "stripe",
    "provider_dispute_id": "dp_1Nxyz",
    "reason": "Issuer chargeback 10.4"
  }
}

`transaction.blocked` (assess decline)

{
  "event": "transaction.blocked",
  "timestamp": "2026-07-05T18:30:00.000Z",
  "data": {
    "session_id": "ps_1716998400000_abc",
    "order_id": "ORD-2024-991",
    "payment_id": "pi_3Nxyz",
    "decision": "decline",
    "risk_score": 100,
    "blocked_by": "Email blocked: reported as chargeback",
    "assess_response": {
      "decision": "decline",
      "session_id": "ps_1716998400000_abc",
      "order_id": "ORD-2024-991"
    }
  }
}

`fraud.detected` (report-fraud)

{
  "event": "fraud.detected",
  "timestamp": "2026-07-05T18:30:00.000Z",
  "data": {
    "case_id": "b1f2...",
    "reference_number": "CLM-LX9A2B",
    "transaction_id": "uuid-clausum-tx",
    "payment_id": "pi_3Nxyz",
    "reason": "chargeback",
    "amount": 89900,
    "currency": "USD",
    "email": "fraudster@example.com",
    "blocklist_entries": 2
  }
}

transaction_id es el UUID interno de Clausum. Las referencias de comercio usan order_id / payment_id del assess.

Headers de firma

Cada entrega incluye:

Header	Descripción
`X-Clausum-Signature`	`t=<unix>,v1=<hmac_sha256_hex>`
`X-Clausum-Event`	Tipo de evento
`X-Clausum-Timestamp`	Hora de entrega ISO 8601

Entrega y reintentos

Haz timeout de tu handler rápido; responde 2xx y procesa de forma asíncrona.
Las entregas fallidas se reintentan vía jobs en background (típicamente cada pocos minutos).
Monitorea intentos recientes en Conexiones → Monitor → Entregas de webhooks salientes.

Haz los handlers idempotentes — deduplica por session_id, order_id, case_id, más event.

Primeros pasos

Integración por tipo de cliente

Soluciones y prevención

Capacidades — eventos y operaciones

Panel de control

Conceptos clave

Referencia

Eventos webhook

Catálogo de eventos (16 eventos)

Ejemplos de payload

`transaction.created` (assess approve / review / challenge)

`case.recommended`

`assess.outcome_applied`

`transaction.blocked` (assess decline)

`fraud.detected` (report-fraud)

Headers de firma

Entrega y reintentos

Relacionado

​Catálogo de eventos (16 eventos)

​Ejemplos de payload

​transaction.created (assess approve / review / challenge)

​case.recommended

​assess.outcome_applied

​transaction.blocked (assess decline)

​fraud.detected (report-fraud)

​Headers de firma

​Entrega y reintentos

​Relacionado

Catálogo de eventos (16 eventos)

Ejemplos de payload

`transaction.created` (assess approve / review / challenge)

`case.recommended`

`assess.outcome_applied`

`transaction.blocked` (assess decline)

`fraud.detected` (report-fraud)

Headers de firma

Entrega y reintentos

Relacionado