## Objetivo

Ingerir eventos Stripe con verificación de firma, deduplicación por evento y replay controlado para recuperación de incidentes.

## Endpoints principales

| Endpoint | Uso | Seguridad |
| --- | --- | --- |
| `POST /api/webhooks/stripe?org={slug}&mode={test\|live}` | ingesta general de eventos Stripe y deduplicación técnica | firma Stripe obligatoria |
| `POST /api/webhooks/stripe/billing?org={slug}&mode={test\|live}` | eventos de billing/suscripciones | firma Stripe obligatoria |
| `POST /api/billing/webhooks/{webhookEventId}/replay?org={slug}&mode={test\|live}` | replay manual de un webhook ya guardado | bearer token Beacon + `OWNER`/`ADMIN` |

## Modelo de procesamiento

<Steps>
  <Step title="1) Recibir evento">Validar firma y estructura mínima del payload.</Step>
  <Step title="2) Deduplicar">Usar `event.id` del proveedor como clave de deduplicación; los duplicados devuelven `duplicate: true`.</Step>
  <Step title="3) Persistir y procesar">Guardar `webhookEventId` interno y ejecutar handlers asíncronos de forma segura.</Step>
  <Step title="4) Confirmar estado">Actualizar estado funcional y métricas de entrega; billing puede hacer upsert de suscripciones.</Step>
</Steps>

## URLs canónicas por entorno

- `test`: `https://test.beacon.pt/api/webhooks/stripe?org=<organization_slug>&mode=test`
- `live`: `https://app.beacon.pt/api/webhooks/stripe?org=<organization_slug>&mode=live`
- Si usas el endpoint dedicado de billing, mantén la misma convención en `/api/webhooks/stripe/billing`.

## Política de retries y replay

- Los retries automáticos deben preservar el contexto original.
- El replay manual usa el identificador interno `webhookEventId`, no el `event.id` de Stripe.
- Evita replay masivo sin priorización por impacto y criterios de validación explícitos.

## Ejemplo de respuesta del endpoint general

```json
{
  "ok": true,
  "webhookEventId": "whevt_123",
  "eventId": "evt_123",
  "mode": "test",
  "duplicate": false
}
```

## Ejemplo de replay manual

```bash
curl -X POST "https://test.beacon.pt/api/billing/webhooks/whevt_123/replay?org=acme&mode=test" \
  -H "Authorization: Bearer <beacon_session_token>"
```

## Señales operativas

| Señal | Significado | Acción |
| --- | --- | --- |
| subida de `4xx` | fallo de firma/payload | revisar secreto y contrato del endpoint |
| backlog creciente | consumer lento o bloqueado | aumentar capacidad y priorizar eventos críticos |
| efectos duplicados | deduplicación insuficiente | reforzar clave por `event.id` + organización |

<Warning title="Replay">El replay debe ser auditable y reversible antes de ejecutarse a gran escala.</Warning>