Saltar al contenido principal
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 token de Access Manager. 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). Si una suscripción no eliminada ya tiene el nombre, la creación devuelve 409 subscription_name_taken.
  • 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: las claves para entregar. Toma cada clave del campo eventKey de GET /v1/catalog, exactamente como se sirve. El hub rechaza una clave que el catálogo no lista en el schema major en el que la suscripción la recibe, con 422 unknown_event_type. Cuando origin está definido, la entrada del catálogo debe venir de ese productor. Cuando el catálogo no se puede leer o todavía no lista ningún evento de productor, el hub acepta las claves sin comprobarlas. Omite el campo para recibir todos los tipos de evento.
  • schema_major: la versión major del payload que sigue la suscripción. Omítelo para seguir la versión major 1.
  • event_majors: un mapa opcional de tipo de evento a schema major, por ejemplo {"loan_application.disbursed": 2}. Reemplaza schema_major para los tipos que nombra. Cuando event_types lista tipos, cada clave debe ser uno de ellos.
  • timeout_ms: solo para un webhook, el timeout de entrega por intento, de 1000 a 20000 milisegundos. El valor predeterminado es 10000.
  • 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. 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. Si la consulta DNS del propio hub falla o vence, responde 503 dns_unavailable o 504 dns_timeout y no escribe nada: reintenta con la misma clave. La respuesta devuelve la nueva suscripción en pending_verification, y el secreto de firma.
  2. Guarda el secreto de firma: ninguna ruta de lectura lo devuelve. Un reintento con la misma clave X-Idempotency devuelve la misma respuesta. El hub guarda el secreto solo como texto cifrado. 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. Un sondeo fallido trae un detail que dice por qué falló. Despliega tu endpoint antes de hacer ping: debe responder 2xx.
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 mueve la suscripción a active.
  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. El hub llega a tu cuenta asumiendo tu rol bajo 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 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.
Solo una suscripción de webhook tiene secreto de firma. El hub rechaza la rotación para cada otro tipo de sink. 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 rehabilita la suscripción, y mueve un estado de verificación active a degraded. 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. Sus conteos cubren el intervalo de window_start a snapshot_at. Límites iguales significan que el hub no guarda historial de entrega, no que la entrega esté sana.

​
Cambio de la fijación del esquema y del timeout

PATCH /v1/subscriptions/:id cambia dos campos. Cada cuerpo debe llevar schema_major:
  • {"schema_major": 2} fija la suscripción a esa versión major.
  • {"schema_major": null} borra la fijación, así que la suscripción sigue la versión major 1.
  • En un webhook, agrega "timeout_ms" para cambiar el timeout por intento, o envía 0 para volver al valor predeterminado de 10000. Envía el schema_major actual con él para mantener la fijación.
El hub rechaza cualquier otro campo, un cuerpo sin schema_major o un schema_major por debajo de 1. Nunca los ignora en silencio, así que nunca puedes creer que un cambio prohibido tuvo efecto. También responde 422 unknown_event_type cuando el nuevo pin deja un tipo de evento guardado sin entrada en el catálogo en su major. Los campos event_types, event_majors y origin son inmutables. Crea una suscripción nueva cuando alguno de ellos deba cambiar. Un PATCH nunca cambia el endpoint, el tipo de sink ni el secreto. 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 devuelva el secreto original en lugar de generar uno nuevo.
  • Reenviar una clave ya confirmada dentro de su ventana de retención (24 horas de forma predeterminada) devuelve la respuesta original byte por byte, con X-Idempotency-Replayed: true.
  • Reusar una clave mientras su primera solicitud sigue en curso, o con un cuerpo de solicitud distinto, devuelve 409 idempotency_conflict. Genera una clave nueva para una solicitud corregida.
  • Una mutación que pudo confirmarse sin un resultado registrado responde 500 idempotency_outcome_unrecorded. Un envío posterior con esa clave puede responder 409 idempotency_outcome_unrecorded. Lee el recurso antes de enviar cualquier cosa de nuevo.
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.