> ## 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. # Inicio rápido > De cero a un evento recibido: crea una suscripción, activa el destino, dispara un evento y confirma la entrega. 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 ` 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](/es/streaming-hub/operating-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](/es/streaming-hub/operating-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](/es/reference/byoc-configuration#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](/es/streaming-hub/operating-streaming-hub) enuncia esa regla. ## Las cinco llamadas *** ``` 1. GET /v1/catalog → lo que declaran tus manifiestos de productor 2. POST /v1/subscriptions → id + signingSecret 3. POST /v1/subscriptions/{id}/ping → active 4. POST /v1/organizations (Midaz) → emite organization.created 5. GET /v1/subscriptions/{id}/health → una entrega exitosa ``` ## 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](/es/reference/events/overview). 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. ```json theme={null} { "name": "quick-start", "sink_kind": "webhook", "endpoint": "https://hooks.example.com/lerian", "event_types": ["organization.created"] } ``` `event_types` contiene **claves de coincidencia**, no tipos CloudEvents completos. Una clave de coincidencia es la cola `.` — `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](/es/reference/events/overview) describen cada tipo en detalle — empieza por el [catálogo de eventos de Midaz](/es/reference/events/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: ```json theme={null} { "outcome": "ok", "statusCode": 200, "errorClass": "" } ``` `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](/es/streaming-hub/managing-subscriptions) 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` ```json theme={null} { "legalName": "Quick Start Ltda", "legalDocument": "00000000000191" } ``` 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](/es/streaming-hub/consuming-events) 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` | Campo | Qué te dice | | -------------------- | --------------------------------------------------------- | | `verification_state` | `active` una vez que el ping tuvo éxito. | | `status` | El veredicto consolidado: `Healthy`, `Degraded` o `Down`. | | `delivery_outcomes` | Conteos de intentos de la ventana, por resultado. | | `last_success_at` | Cuándo tuvo éxito la última entrega. | | `dead_lettered` | Intentos que agotaron sus reintentos. | 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=`. La lectura es el acuse, así que lee las reglas del cursor en [Consumo de eventos](/es/streaming-hub/consuming-events) antes de tu primera llamada. ## Próximos pasos *** Sinks de cola, grants delegados de AWS, rotación de secretos y recuperación. Verifica firmas, deduplica entregas y haz pull con un cursor. Matching, despacho, la curva de reintentos y el auto-disable. Despliega el hub, configúralo y obsérvalo funcionar.