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 o una edició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: En BYOC, un endpoint de webhook o un broker RabbitMQ en una dirección privada funciona cuando la operación de Lerian autoriza el host. En RabbitMQ, la autorización también cubre el puerto AMQP. El hub multi-tenant rechaza un broker RabbitMQ privado. SQS y EventBridge nunca reciben una autorización.
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 de pending_verification a active cuando un sondeo tiene éxito. Un sondeo fallido solo reporta el resultado y no cambia ningún estado. Solo una suscripción active es entregable.
  • enabled es el interruptor de entregabilidad. Es la desactivación automática y una pausa lo apagan. Una rehabilitación o una reanudación lo 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. La lista y la lectura individual también devuelven paused. Es true después de que pausas la suscripción, y enabled queda en false. Una suscripción que el hub detuvo se lee como enabled = false, paused = false, así que paused distingue las dos. verify rehabilita una suscripción detenida, y resume reanuda una suscripción en pausa. El status de la salud de entrega muestra Paused para una suscripción en pausa. La lista y la lectura individual también devuelven last_success_at y last_failure_at. last_success_at es la última entrega exitosa, o la disponibilidad de pull en una suscripción pull. last_failure_at es la última entrega fallida desde ese éxito. Un éxito lo borra, y lo mismo hacen una verificación que rehabilita la suscripción, una reanudación y una edición que mueve el endpoint. Así que, cuando last_failure_at está presente, el destino está fallando. El hub omite un campo que no tiene valor.

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.
No es obligatorio hacer ping. El hub también sondea por su cuenta un webhook en pending_verification, salvo que la suscripción esté en pausa. El primer sondeo llega alrededor de 1 minuto después de la creación, y el intervalo se duplica hasta 1 hora. Un sondeo exitoso activa la suscripción y emite hub.destination.verified. Mientras la suscripción está pendiente, el hub no le entrega ningún evento, y su lectura muestra last_probe_at, last_probe_outcome, last_probe_error_class y next_verification_attempt_at. 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. PUT /credential solo comprueba que el hub pueda conectarse y autenticarse. POST /verify también comprueba el destino al que entrega la suscripción. Un destino eliminado, o una credencial que carece de un permiso de esta tabla, hace fallar el verify:

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 y no cambia verification_state. El hub rechaza, con 422, un rol cuya política de confianza no exige el ExternalId. Cuando AWS no puede responder esa comprobación, la solicitud falla con 500 y no escribe nada.
  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. Una suscripción que pausaste también se lee con enabled = false, con paused = true. verify no la rehabilita: reanúdala. Para recuperar una suscripción desactivada automáticamente:
  1. Corrige el destino (el endpoint, la cola o la concesión). Para pasar a un endpoint nuevo, edita la suscripción. El endpoint nuevo debe responder al sondeo, y la edición mantiene enabled = false.
  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. Una suscripción de cola se sondea con la concesión delegada, cuando tiene una, y si no con la credencial guardada.
Un resondeo fallido no rehabilita la suscripción y no cambia ningún estado. PUT /v1/subscriptions/:id/credential tampoco la rehabilita: llama a verify después. 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.

Edición de una suscripción

PATCH /v1/subscriptions/:id edita una suscripción en su lugar. La suscripción conserva su id, su secreto de firma o su credencial de cola, su tipo de sink, su origin y su plan_tier. Envía un header X-Idempotency. Cada cuerpo debe llevar schema_major. Cada otro campo es opcional, y solo cambia lo que envías:
  • 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. Cada edición reescribe la fijación. Envía el valor que muestra una lectura, o null cuando la lectura no muestra ninguna fijación.
  • name: el nombre nuevo.
  • endpoint: el destino nuevo. El hub lo rechaza en una suscripción pull.
  • event_types: la lista nueva, que reemplaza a la anterior. [] o ["*"] significa todos los eventos.
  • event_majors: el mapa nuevo, que reemplaza todo el mapa anterior. {} lo borra. Cuando event_types es una lista explícita, cada clave debe ser uno de sus tipos. Cuando quitas un tipo que tiene un override, envía event_majors sin esa clave en la misma solicitud.
  • timeout_ms: en un webhook, el timeout por intento. Envía 0 para volver al valor predeterminado de 10000.
El hub comprueba los valores nuevos como lo hace una creación. Un endpoint nuevo pasa por las mismas comprobaciones de destino y por la misma consulta DNS, y un fallo de DNS responde 503 dns_unavailable o 504 dns_timeout. Un tipo de evento sin entrada en el catálogo responde 422 unknown_event_type. Un nombre que otra suscripción activa de tu ámbito ya usa responde 409 subscription_name_taken. El hub rechaza con 422 cualquier otro campo, un cuerpo sin schema_major o un schema_major por debajo de 1. El secreto cambia solo con la rotación. Una suscripción activa pasa a un endpoint nuevo solo después de que el destino nuevo responde a un sondeo hecho con el secreto o la credencial guardados. Un sondeo fallido responde 422 destination_probe_failed con su error_class, y con status_code en un webhook. No cambia nada. Una suscripción que espera verificación guarda el endpoint nuevo sin sondeo, y el hub la verifica como a una suscripción nueva. Una edición nunca cambia verification_state ni enabled, y deja en pausa una suscripción en pausa. GET /v1/subscriptions/:id devuelve un ETag. Envíalo de vuelta como If-Match en la edición. Cuando la suscripción cambió después de tu lectura, el hub responde 412 subscription_changed y no cambia nada. Cualquier cambio cuenta, incluida una pausa, una rotación, un sondeo correcto o una desactivación automática. Vuelve a leer la suscripción y envía la edición con una nueva clave X-Idempotency. Una edición de endpoint en una suscripción que espera verificación también puede responder 412 sin If-Match, cuando un sondeo verifica la suscripción entre la lectura del hub y su escritura. Un If-Match mal formado responde 400 bad_request.

Pausa y reanudación de una suscripción

Detienes y reinicias la entrega a una suscripción con dos llamadas. Ninguna lleva el header X-Idempotency, y las dos requieren el permiso subscriptions post. Las dos responden 200 sin cuerpo, y repetir una es una operación nula que también responde 200.
  • POST /v1/subscriptions/:id/pause detiene la entrega de inmediato y cancela las entregas que esperan en la cola. La suscripción se lee con enabled = false y paused = true. Un intento de entrega que ya está en curso todavía puede llegar.
  • POST /v1/subscriptions/:id/resume entrega los eventos que llegan al hub después de la reanudación, y solo esos. También borra el historial de fallos, así que el tiempo en pausa nunca cuenta para la desactivación automática.
Una suscripción push (webhook, sqs, rabbitmq, eventbridge) no recibe los eventos que llegan al hub mientras está en pausa, y una reanudación no los envía. Una suscripción pull en pausa lee páginas vacías. Una reanudación mueve su posición de lectura al evento más reciente, así que se omite todo evento que aún no había leído. ?after= todavía lee eventos más antiguos dentro de la retención. Consulta lectura de eventos por pull. Una suscripción que el hub detuvo tras fallos repetidos responde 409 subscription_stopped_by_hub a las dos llamadas. Llama a POST /v1/subscriptions/:id/verify en su lugar. verify nunca reanuda una suscripción en pausa. Un ping o un verify en una suscripción en pausa registra el sondeo y deja la suscripción en pausa. Cuando la suscripción esperaba verificación, un sondeo exitoso la activa, y el hub no emite hub.destination.verified.

Suscripciones de socios de Consignado

Un fondo u originador de Consignado gestiona sus propias suscripciones push mediante el gateway de Consignado. El gateway retransmite las llamadas del socio: crear, listar, leer, editar, pausar, reanudar, ping, rotar el secreto de firma, leer la salud y eliminar. Un socio alcanza solo las suscripciones que creó y no puede crear una suscripción pull. La retransmisión funciona cuando STREAMING_HUB_PARTNERS_URL está definida. Sin ella, el hub rechaza cada llamada retransmitida con 403 delegated_relay_refused. Una suscripción de socio entrega solo mientras Access Manager muestra al socio como activo.

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) y las rutas pause y resume 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.