> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # Gestión de suscripciones > Crea suscripciones de webhook y de cola en Streaming Hub, conecta una concesión delegada de AWS, rota secretos de firma, recupera destinos desactivados y vuelve a fijar. Una **suscripción** le dice a Streaming Hub qué eventos van a qué destino para tu tenant. Gestionas las suscripciones con la API `/v1` del plano de control, autenticada con un JWT de plugin-auth. Esta página cubre el modelo y los flujos de incorporación. La referencia de API tiene las formas exactas de solicitud y de respuesta (empieza por la [introducción a la referencia](/es/reference/introduction)). ## El modelo de suscripción *** Una suscripción registra: * **`name`**: una etiqueta legible para personas (obligatorio, no vacío). * **`sink_kind`**: uno de `webhook`, `pull`, `sqs`, `rabbitmq`, `eventbridge`. * **`endpoint`**: a dónde van las entregas, en una forma que depende del tipo de sink (ver abajo). * **`event_types`**: claves `.` sin fuente para entregar. El hub acepta cualquier clave bien formada, así que un hueco en el catálogo nunca detiene la incorporación. Una clave que ningún productor emite no coincide con nada. Toma cada clave de las páginas por producto en [Event streaming](/es/reference/events/overview). * **`origin`**: una fijación exacta y opcional de `ce-source`. Omítela para aceptar la misma clave de cualquier aplicación productora. * **`schema_major`**: la versión major del payload que sigue la suscripción. * **`plan_tier`**: el nivel de entrega bajo el que corre la suscripción. El formato del endpoint sigue al tipo de sink: | Tipo de sink | Endpoint | | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | `webhook` | Una URL `https://`, sin userinfo incrustado. | | `pull` | Se omite: el servidor sintetiza `pull://`. | | `sqs` | La URL `https://` de la cola SQS. | | `rabbitmq` | `/` (exchange obligatorio, routing key opcional). El host del broker vive en la credencial cifrada. | | `eventbridge` | El nombre del bus de eventos de EventBridge. `DetailType` se deriva del tipo de evento que coincidió. La región vive en la credencial cifrada. | La entrega a cola no conserva el `ce-type` canónico calificado por fuente. SQS y RabbitMQ definen `ce-type` como la clave simple `.`. EventBridge usa esa clave simple para `DetailType` y `Detail.type`, y su `source` identifica al hub en lugar del productor. Fija `origin` y conserva la identidad de la suscripción junto a la entrega cuando la identidad del productor importa. ### Dos campos de estado ortogonales *** Cada suscripción lleva dos campos de estado independientes. Confundirlos es la fuente más común de preguntas del tipo "por qué se detuvo la entrega", así que mantenlos separados: * **`verification_state`** es la **prueba** de que el destino puede recibir eventos de verdad. Pasa por `pending_verification` → `active` → `degraded`, impulsado por sondeos. Solo una suscripción `active` es entregable. * **`enabled`** es el **interruptor de entregabilidad**. Es lo que la desactivación automática apaga y lo que una rehabilitación vuelve a encender. La coincidencia de suscripciones requiere **ambos**: una suscripción entrega solo cuando está `enabled` **y** `verification_state = active`. La desactivación automática vive por completo en `enabled` y nunca cambia `verification_state`, así que una suscripción desactivada automáticamente se lee como `enabled = false, verification_state = active`. Consulta [desactivación automática de un destino roto](/es/platform/streaming-hub/how-streaming-hub-works) para ver cómo interactúan los dos. ## Creación de una suscripción de webhook *** Una suscripción de webhook es la más simple de incorporar. No necesita credencial, solo un sondeo: 1. **Crea**: `POST /v1/subscriptions` con `sink_kind: "webhook"` y tu endpoint `https://`. Envía un header `X-Idempotency` único: el hub rechaza una creación que lo omite, antes de cualquier escritura. El hub valida la URL del destino contra rangos de direcciones privadas, de loopback y de metadatos de nube antes de cualquier escritura. Nunca guarda un destino privado o de metadatos. La respuesta devuelve la nueva suscripción en **`pending_verification`**, y el **secreto de firma exactamente una vez**. 2. **Guarda el secreto de firma**: solo esta respuesta lo muestra. El hub lo guarda solo como texto cifrado, y ninguna lectura lo devuelve. Guárdalo al recibirlo. Si lo pierdes, solo puedes rotar a uno nuevo. 3. **Activa el destino**: `POST /v1/subscriptions/:id/ping` envía un sondeo sintético y firmado por la ruta de entrega real, e informa el resultado clasificado. Un sondeo exitoso mueve la suscripción a `active`, y eso es lo que la hace entregable. Despliega tu endpoint antes de hacer ping: debe responder `2xx`. El hub devuelve el secreto de firma solo en la respuesta de creación, y otra vez en la rotación. El hub nunca lo registra en logs, nunca lo guarda en texto plano y nunca lo devuelve desde un `GET`. Cáptalo cuando creas la suscripción. Después de que el sondeo tiene éxito, la coincidencia admite la suscripción de webhook y empieza a recibir eventos. Para el recorrido completo desde la creación hasta una primera entrega confirmada, consulta el [inicio rápido](/es/platform/streaming-hub/streaming-hub-quick-start). Consulta [Consumo de eventos](/es/platform/streaming-hub/consuming-events) para saber cómo verificar la firma en cada entrega. ## Incorporación de una suscripción de cola *** Las suscripciones de cola (`sqs`, `rabbitmq`, `eventbridge`) nacen en **`pending_verification`** y **no entregan nada** hasta que un sondeo verifica su destino. Cómo verificas depende del tipo: * **RabbitMQ**: entrega una credencial de broker, verificada en la escritura (abajo). * **SQS y EventBridge**: entrega una credencial de salida, verificada en la escritura (abajo), o [conecta una concesión delegada de AWS](#wiring-an-aws-delegated-grant) (siguiente sección) sin guardar una credencial. Para cualquier tipo de cola, el flujo de credencial de salida tiene tres pasos: 1. **Crea**: `POST /v1/subscriptions` con el `sink_kind` de cola y su endpoint, y **sin** credencial en línea (el hub rechaza un `sink_config` o `credential` en línea). Envía un header `X-Idempotency` único, como en cualquier creación. El hub guarda la suscripción en `pending_verification`. La coincidencia la excluye, así que todavía no produce trabajos de entrega. 2. **Entrega la credencial**: `PUT /v1/subscriptions/:id/credential` con la credencial de salida de solo escritura. El hub la mantiene en memoria, la **sondea de inmediato** (se conecta y se autentica contra el destino) y la persiste como texto cifrado **solo si el sondeo tiene éxito**. Un sondeo fallido no guarda nada. El hub valida las direcciones de destino contra los rangos bloqueados antes de guardarlas. Un sondeo exitoso cambia la suscripción `pending_verification → active` en la misma transacción. 3. **Activa**: una vez en `active`, la coincidencia admite la suscripción y empieza a recibir eventos. La credencial es de **solo escritura**: la entregas aquí y ninguna ruta de lectura la devuelve, ni siquiera enmascarada. Para cambiarla, haz `PUT` de una nueva. Se aplica el mismo sondeo en la escritura.

Conexión de una concesión delegada de AWS

*** Para el camino de AWS sin credenciales (`sqs`, `eventbridge`), el hub entrega asumiendo un rol **en tu cuenta de AWS**. Conectas esa confianza en lugar de entregar una credencial de salida: 1. **Trae los artefactos de configuración**: `GET /v1/subscriptions/:id/setup-artifacts` devuelve una **política de confianza** de IAM entre cuentas, un **enlace de creación rápida** de CloudFormation y un **`ExternalId`** no secreto que el hub genera para esta suscripción. 2. **Aplícalos en tu cuenta de AWS**: crea el rol de entrega a partir de la política de confianza (el enlace de creación rápida lo arma). El rol confía en el principal del hub *solo* bajo la condición del `ExternalId` generado. Esa condición cierra la brecha del confused deputy. Una política de confianza que la omite falla la verificación, y nunca cuenta como verificada. 3. **Registra la concesión**: `PUT /v1/subscriptions/:id/delegated-grant` con el ARN del rol de entrega, la región y el destino. Esto registra solo coordenadas no secretas. No ejecuta ningún sondeo y no cambia `verification_state`. 4. **Verifica**: `POST /v1/subscriptions/:id/verify` ejecuta el sondeo endurecido de asunción de rol y, si tiene éxito, cambia la suscripción a `active`. Ninguna credencial de AWS cruza estas solicitudes, y el hub nunca guarda una. El hub asume tu rol en cada entrega, protegido por el `ExternalId`. ## Rotación de un secreto de firma *** `POST /v1/subscriptions/:id/secret/rotate` genera un secreto de firma de webhook **nuevo**, lo devuelve **una vez** y empieza un **solapamiento de doble firma de 24 horas**. Durante el solapamiento el hub firma cada entrega con **ambos** secretos, el nuevo y el anterior, y envía **dos** headers de firma. Por eso tu consumidor puede cambiar al secreto nuevo en cualquier punto de la ventana sin perder entregas. Rota de forma limpia así: 1. Llama a rotate y guarda el secreto nuevo de la respuesta (junto con la marca de tiempo `overlapUntil`). 2. Despliega el secreto nuevo en tu consumidor dentro de la ventana de solapamiento. Mientras tu verificador tiene los dos secretos, acepta una entrega si **alguna** de las firmas valida. 3. Después del solapamiento, retira el secreto viejo. Un sink `pull` no tiene secreto de firma, así que el hub rechaza la rotación. Consulta [manejo de dos firmas durante la rotación](/es/platform/streaming-hub/consuming-events) para la verificación del lado del consumidor. ## Recuperación de una suscripción desactivada automáticamente *** Cuando un destino sigue roto el tiempo suficiente, el hub [desactiva automáticamente](/es/platform/streaming-hub/how-streaming-hub-works) la suscripción cambiándola a `enabled = false`. Para recuperarla: 1. Corrige el destino (el endpoint, la cola o la concesión). 2. Llama a `POST /v1/subscriptions/:id/verify`. Vuelve a sondear el destino. Si el sondeo tiene éxito, vuelve a habilitar la suscripción y borra la marca de desactivación automática, en su lugar y con el mismo id y secreto de firma. Un resondeo fallido no cambia nada, así que la rehabilitación siempre queda atada a un sondeo exitoso real y actual. Llama a `GET /v1/subscriptions/:id/health` para el resumen de salud de entrega (resultados recientes, conteos de dead-letter y el veredicto de desactivación automática). Úsalo para confirmar que el destino está sano antes y después. ## Cambio de fijación del major de esquema *** `PATCH /v1/subscriptions/:id` vuelve a fijar el `schema_major` de la suscripción, el **único** campo mutable: * `{"schema_major": 2}` fija la suscripción a esa versión major. * `{"schema_major": null}` borra la fijación para seguir la versión base. El hub **rechaza** cualquier otro campo, un cuerpo vacío o un valor por debajo de `1`. Nunca los ignora en silencio, así que nunca puedes creer que un cambio prohibido tuvo efecto. Los campos `event_types` y `origin` son inmutables. Crea una suscripción nueva cuando alguno de los dos filtros deba cambiar. Cambiar el endpoint, el tipo de sink o el secreto también queda fuera del alcance de `PATCH` por diseño. Volver a fijar no es un cambio de destino. No reinicia `verification_state` ni devuelve ningún secreto. ## Idempotencia *** Las rutas que mutan (crear, borrar, `PATCH`, rotar el secreto y registrar la concesión delegada) requieren una clave de idempotencia: ``` X-Idempotency: ``` El hub rechaza una mutación enviada sin ella **antes de cualquier escritura**, con `400 missing_idempotency_key`. El almacén **falla en cerrado**: si el almacén de idempotencia no está disponible, la solicitud falla en lugar de arriesgar una escritura doble. Eso garantiza que una creación o una rotación reenviada vuelva a servir el secreto original mostrado una sola vez, en lugar de generar uno nuevo. * Reenviar una clave ya confirmada devuelve la respuesta original byte por byte, con `X-Idempotency-Replayed: true`. * Reusar una clave con un cuerpo de solicitud *distinto* devuelve `409 idempotency_conflict`. Genera una clave nueva para una solicitud corregida. Las rutas de verificación (`ping`, `verify`, `PUT /credential`, `GET /setup-artifacts`) son idempotentes por naturaleza y no requieren clave. Consulta la guía de toda la plataforma sobre [reintentos e idempotencia](/es/reference/retries-idempotency). ## Próximos pasos *** Verifica firmas de webhook, deduplica entregas y lee eventos con pull. Coincidencia, despacho, reintentos y desactivación automática en detalle.