> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clausum.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Eventos webhook

> El catálogo de eventos que Clausum entrega a tus endpoints.

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](/es/guides/receiving-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)

```json theme={null}
{
  "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`

```json theme={null}
{
  "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`

```json theme={null}
{
  "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)

```json theme={null}
{
  "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)

```json theme={null}
{
  "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**.

<Tip>
  Haz los handlers **idempotentes** — deduplica por `session_id`, `order_id`, `case_id`, más `event`.
</Tip>

## Relacionado

* [Retroalimentación de outcome assess](/es/guides/assess-outcome-feedback)
* [Recibir webhooks](/es/guides/receiving-webhooks)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.