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

# Stripe webhooks (native)

> Receive Stripe charge, dispute, and Radar events through Clausum's unified inbound pipeline.

Clausum exposes a **native Stripe webhook URL** (recommended over generic ingest for Stripe). Events are verified, stored, linked to sessions/cases, and may trigger **outbound** merchant webhooks.

## Configure in Stripe

1. In the dashboard: **Conexiones → Entrada (webhooks)** — copy the Stripe endpoint URL.
2. In [Stripe Dashboard → Webhooks](https://dashboard.stripe.com/webhooks), add endpoint:

```
https://{your-api-host}/api/webhooks/stripe?org_id={your_profile_uuid}
```

Optional sandbox integration:

```
...?org_id={profile_uuid}&environment=sandbox
```

3. Paste Stripe's **signing secret** into your Clausum Stripe integration config (`webhook_secret`).

<Note>
  `org_id` is your tenant **profile UUID** (same id used when provisioning integrations), not the organizations table id shown in some admin screens.
</Note>

## Supported events

| Stripe event                        | Clausum handling                                                                         |
| ----------------------------------- | ---------------------------------------------------------------------------------------- |
| `charge.succeeded`                  | Links `metadata.clausum_session_id` to payment session; outbound `transaction.succeeded` |
| `charge.dispute.created`            | Case + outbound `dispute.created` / case events                                          |
| `charge.dispute.updated` / `closed` | Case update; outbound `dispute.updated` / `dispute.resolved`                             |
| `radar.early_fraud_warning.created` | Auto case + outbound `case.created`                                                      |
| `payment_intent.payment_failed`     | Outbound `transaction.failed`                                                            |

Verify pipeline version:

```bash theme={null}
curl -s "$CLAUSUM_API_BASE/api/webhooks/stripe" | jq '{version, pipeline}'
```

Expected: `"version": "2.0"`, `"pipeline": "processProviderInboundWebhook"`.

## Link checkout sessions

When creating a Stripe PaymentIntent or Charge, set metadata:

```json theme={null}
{
  "metadata": {
    "clausum_session_id": "ps_1716998400000_abc"
  }
}
```

Use the `session_id` returned from `POST /api/v1/assess`.

## vs generic ingest

| Approach                        | Use when                                                |
| ------------------------------- | ------------------------------------------------------- |
| **`POST /api/webhooks/stripe`** | Native Stripe — signature verification, disputes, Radar |
| **`POST /api/webhooks/ingest`** | Custom providers, internal ledger events (`clm_wh_*`)   |
| **Mercado Pago / Adyen**        | `/api/webhooks/mercadopago`, `/api/webhooks/adyen`      |

<Warning>
  Do not forward Stripe webhooks to ingest with a **`clm_sk_*`** key. Ingest requires **`clm_wh_*`**. For Stripe, use the native URL above.
</Warning>