Skip to main content
Esta página te lleva de cero a un evento entregado. Usa un sink webhook, porque es el camino más corto: cuatro llamadas al hub y una solicitud HTTP que llega a tu endpoint. Cada llamada /v1 envía Authorization: Bearer <token> y application/json. El hub lee tu tenant del token. Nunca lee un tenant de un cuerpo, una ruta o una query.

​
Antes de empezar

Necesitas cuatro cosas.
  • Un hub en ejecución y un token. El plano de control /v1 autentica cada ruta con un JWT de plugin-auth. La lectura del catálogo de abajo también pide catalog get. Consulta Operación de Streaming Hub para el despliegue.
  • STREAMING_HUB_MANIFEST_SOURCES definido en el hub, si quieres que la lectura del catálogo liste tus productores. Viene vacío por defecto, y una lista vacía deja el catálogo solo con las entradas hub.* del propio hub. Consulta Operación de Streaming Hub.
  • Un endpoint https:// público que controles. El hub valida el destino antes de escribir cualquier fila y rechaza direcciones privadas, de loopback y de metadatos de nube. Un endpoint localhost no se puede almacenar.
  • Un productor en el mismo stream, con la publicación encendida. La publicación viene apagada por defecto del lado del productor. En Midaz, define STREAMING_ENABLED=true, apunta STREAMING_BROKERS a los mismos brokers que STREAMING_HUB_KAFKA_BROKERS, y define STREAMING_CLOUDEVENTS_SOURCE. Consulta Streaming y outbox. El ce-tenantid que emite el productor también debe ser igual al STREAMING_HUB_TENANT_ID del hub. Una discrepancia descarta cada evento sin error. Operación de Streaming Hub enuncia esa regla.

​
Las cinco llamadas

​
1. Obtén la clave de coincidencia

GET /v1/catalog El catálogo lista lo que declaran los manifiestos de productor en STREAMING_HUB_MANIFEST_SOURCES. Cada entrada da un eventType y un topic. El catálogo no lleva la clave de coincidencia. eventType es solo el segmento de evento. El topic pliega el nombre del servicio del productor en su segmento de recurso. Así que lerian.streaming.ledger_organization.created tiene eventType created, y la clave que necesitas es organization.created. Toma la clave de las páginas por producto en Streaming de eventos. El propio /streaming/manifest del productor también reporta resourceType junto a eventType. El hub acepta cualquier clave bien formada en event_types. Una clave que ningún productor emite no coincide con nada, y la suscripción no recibe ningún evento.

​
2. Crea la suscripción

POST /v1/subscriptions Envía el header X-Idempotency con un valor único. El hub rechaza un create que lo omite, antes de cualquier escritura.
event_types contiene claves de coincidencia, no tipos CloudEvents completos. Una clave de coincidencia es la cola <recurso>.<evento> — organization.created, y nunca el tipo completo studio.lerian.organization.created. Envía la clave que armaste en el paso 1. Omite event_types para recibir cada evento que el hub ve. Las páginas por producto bajo Streaming de eventos describen cada tipo en detalle — empieza por el catálogo de eventos de Midaz. plan_tier toma standard por defecto. schema_major es opcional: déjalo fuera para seguir la versión base. La respuesta 201 trae el id de la suscripción y el signingSecret en texto plano. Guarda el secreto ahora. Ninguna ruta de lectura lo devuelve, y si lo pierdes tu única salida es la rotación.

​
3. Activa el destino

POST /v1/subscriptions/{id}/ping Una suscripción de webhook nueva nace en pending_verification. El hub solo le entrega después de que un sondeo pruebe que el destino responde, así que esta llamada es obligatoria. Envía una solicitud sintética y firmada por el camino de entrega de producción, y luego informa el resultado:
outcome: "ok" mueve la suscripción a active, que es el estado que la hace entregable. Tu endpoint debe responder con un 2xx para que eso ocurra, así que despliégalo antes del ping. Un sondeo que corrió y falló sigue siendo un 200: lee outcome, no el estado HTTP. outcome: "failed" deja la suscripción sin verificar y nombra la causa en errorClass. Corrige el endpoint y repite el ping. La llamada es segura de repetir y no necesita clave de idempotencia. La entrega requiere enabled y verification_state = active. Gestión de suscripciones explica por qué los dos campos se mantienen separados.

​
4. Dispara un evento

Haz algo en un producto Lerian que emita el tipo al que te suscribiste. En Midaz, crear una organización emite el evento de arriba. POST /v1/organizations
Midaz publica el evento en el stream justo después de persistir la organización. La entrega llega a tu endpoint momentos después, no dentro de esta llamada.

​
5. Confirma la entrega

Tu endpoint recibe un POST que trae el payload del evento, una firma HMAC y los headers de contexto del hub, entre ellos X-Lerian-Event-Id, X-Lerian-Event-Type y X-Lerian-Delivery-Id. Verifica la firma antes de confiar en el cuerpo: una solicitud sin verificar no prueba nada. Consumo de eventos tiene los pasos de verificación, la lista completa de headers y la regla de deduplicación. Después pregúntale al hub qué registró. GET /v1/subscriptions/{id}/health Un éxito en delivery_outcomes y un last_success_at reciente significan que el camino funciona de punta a punta. Si no llegó nada, status y delivery_outcomes te dicen si el hub intentó y falló, o si nunca hizo match con el evento.

​
¿Prefieres hacer pull?

Una suscripción pull no necesita endpoint ni sondeo. Créala con sink_kind: "pull" y sin endpoint: el hub sintetiza uno, y la suscripción nace active. Lee páginas de eventos con GET /v1/events?subscription_id=<id>. La lectura es el acuse, así que lee las reglas del cursor en Consumo de eventos antes de tu primera llamada.

​
Próximos pasos

Gestión de suscripciones

Sinks de cola, grants delegados de AWS, rotación de secretos y recuperación.

Consumo de eventos

Verifica firmas, deduplica entregas y haz pull con un cursor.

Cómo funciona Streaming Hub

Matching, despacho, la curva de reintentos y el auto-disable.

Operación de Streaming Hub

Despliega el hub, configúralo y obsérvalo funcionar.