> ## 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.

# Webhook events

> The catalog of events Clausum delivers to your endpoints.

Clausum sends outbound webhooks to HTTPS endpoints you configure under **Conexiones → Webhooks salientes** (sandbox and production are separate). Each delivery is an HTTP `POST` with JSON body and HMAC signature headers. See [Receiving webhooks](/guides/receiving-webhooks) for verification and handling.

## Event catalog (11 events)

| Event                   | When it fires                                                                                              |
| ----------------------- | ---------------------------------------------------------------------------------------------------------- |
| `transaction.created`   | After **`POST /api/v1/assess`** (or payout assess) returns **`approve`**, **`review`**, or **`challenge`** |
| `transaction.blocked`   | After assess returns **`decline`**                                                                         |
| `transaction.succeeded` | Inbound payment provider confirms success (Stripe, Mercado Pago, Adyen)                                    |
| `transaction.failed`    | Inbound provider reports payment failure                                                                   |
| `fraud.detected`        | Fraud reported via `POST /api/v1/report-fraud` or equivalent flow                                          |
| `fraud.confirmed`       | Case marked as confirmed fraud in the dashboard                                                            |
| `case.created`          | Case opened automatically (e.g. Stripe dispute, Radar warning)                                             |
| `case.updated`          | Case status or fields changed                                                                              |
| `dispute.created`       | Chargeback / dispute opened                                                                                |
| `dispute.updated`       | Dispute updated while open                                                                                 |
| `dispute.resolved`      | Dispute closed (won, lost, or withdrawn)                                                                   |

Subscribe only to events your backend will handle — the dashboard checkbox list matches this catalog exactly.

## Payload examples

### `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": []
    }
  }
}
```

### `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` is the **Clausum internal** UUID. Merchant references use `order_id` / `payment_id` from assess.

## Signature headers

Every delivery includes:

| Header                | Description                     |
| --------------------- | ------------------------------- |
| `X-Clausum-Signature` | `t=<unix>,v1=<hmac_sha256_hex>` |
| `X-Clausum-Event`     | Event type                      |
| `X-Clausum-Timestamp` | ISO 8601 delivery time          |

## Delivery & retries

* Time out your handler quickly; respond **`2xx`** and process asynchronously.
* Failed deliveries are retried via background jobs (typically every few minutes).
* Monitor recent attempts in **Conexiones → Monitor → Entregas webhook salientes**.

<Tip>
  Make handlers **idempotent** — dedupe on `session_id`, `order_id`, `case_id`, plus `event`.
</Tip>