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

# Webhooks Stripe (nativo)

> Adaptador Stripe opcional — eventos de cargo, disputa y Radar con firma verificada.

<Note>
  El **camino inbound por defecto** para cualquier procesador (incluido Stripe) es [Ingestión de eventos](/es/guides/event-ingestion) con `clm_wh_*`. Usa este **adaptador nativo opcional de Stripe** cuando quieras verificación de firma Stripe y automatización de disputas/Radar sin mapear eventos tú mismo.
</Note>

Clausum expone una **URL webhook nativa de Stripe**. Los eventos se verifican, almacenan, vinculan a sesiones/expedientes y pueden disparar webhooks **salientes** de comercio.

## Configurar en Stripe

1. En el panel: **Conexiones → Entrada (webhooks)** → abre **Guías por procesador** → Stripe — copia la URL del endpoint.
2. En [Stripe Dashboard → Webhooks](https://dashboard.stripe.com/webhooks), agrega endpoint:

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

Integración sandbox opcional:

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

3. Pega el **signing secret** de Stripe en la config de integración Stripe de Clausum (`webhook_secret`).

<Note>
  `org_id` es el **UUID de perfil** de tu tenant (mismo id usado al aprovisionar integraciones), no el id de la tabla organizations mostrado en algunas pantallas admin.
</Note>

## Eventos soportados

| Evento Stripe | Manejo Clausum |
| - | - |
| `charge.succeeded` | Vincula `metadata.clausum_session_id` a sesión de pago; outbound `transaction.succeeded` |
| `charge.dispute.created` | Expediente + outbound `dispute.created` / eventos de expediente |
| `charge.dispute.updated` / `closed` | Actualización de expediente; outbound `dispute.updated` / `dispute.resolved` |
| `radar.early_fraud_warning.created` | Expediente auto + outbound `case.created` |
| `payment_intent.payment_failed` | Outbound `transaction.failed` |

Verifica versión del pipeline:

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

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

## Vincular sesiones de checkout

Al crear un PaymentIntent o Charge de Stripe, establece metadata:

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

Usa el `session_id` devuelto por `POST /api/v1/assess`.

## vs ingest genérico

| Enfoque | Usar cuando |
| - | - |
| **`POST /api/webhooks/ingest`** (**por defecto**) | Cualquier procesador o ledger interno — `clm_wh_*` |
| **`POST /api/webhooks/stripe`** (opcional) | Stripe nativo — verificación de firma, disputas, Radar |
| **Otras guías nativas** | Adaptadores Mercado Pago / Adyen bajo Guías por procesador |

<Warning>
  No llames ingest con clave **`clm_sk_*`**. Ingest requiere **`clm_wh_*`**. Las claves de assess e ingest no son intercambiables.
</Warning>


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