Skip to main content
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).

​
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 <resource>.<event> 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.
  • 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:
La entrega a cola no conserva el ce-type canónico calificado por fuente. SQS y RabbitMQ definen ce-type como la clave simple <resource>.<event>. 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 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. Consulta Consumo de eventos 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 (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 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 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:
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.

​
Próximos pasos

Consumo de eventos

Verifica firmas de webhook, deduplica entregas y lee eventos con pull.

Cómo funciona Streaming Hub

Coincidencia, despacho, reintentos y desactivación automática en detalle.