> ## 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. # Início rápido > Do zero a um evento recebido — crie uma assinatura, ative o destino, dispare um evento e confirme a entrega. Esta página leva você do zero a um evento entregue. Ela usa um sink `webhook`, porque é o caminho mais curto: quatro chamadas ao hub e uma solicitação HTTP chegando ao seu endpoint. Cada chamada `/v1` envia `Authorization: Bearer ` e `application/json`. O hub lê o seu tenant do token. Ele nunca lê um tenant de um corpo, de uma rota ou de uma query. ## Antes de começar *** Você precisa de quatro coisas. * **Um hub em execução e um token.** O plano de controle `/v1` autentica cada rota com um JWT do plugin-auth. A leitura do catálogo abaixo também pede `catalog` `get`. Veja [Operando o Streaming Hub](/pt/streaming-hub/operating-streaming-hub) para o deploy. * **`STREAMING_HUB_MANIFEST_SOURCES` definido no hub**, se você quiser que a leitura do catálogo liste os seus produtores. Ele vem vazio por padrão, e uma lista vazia deixa o catálogo apenas com as entradas `hub.*` do próprio hub. Veja [Operando o Streaming Hub](/pt/streaming-hub/operating-streaming-hub). * **Um endpoint `https://` público que você controla.** O hub valida o destino antes de gravar qualquer linha e rejeita endereços privados, de loopback e de metadados de nuvem. Um endpoint `localhost` não pode ser armazenado. * **Um produtor no mesmo stream, com a publicação ligada.** A publicação vem desligada por padrão do lado do produtor. No Midaz, defina `STREAMING_ENABLED=true`, aponte `STREAMING_BROKERS` para os mesmos brokers que `STREAMING_HUB_KAFKA_BROKERS`, e defina `STREAMING_CLOUDEVENTS_SOURCE`. Veja [Streaming e outbox](/pt/reference/byoc-configuration#streaming-e-outbox). O `ce-tenantid` que o produtor emite também precisa ser igual ao `STREAMING_HUB_TENANT_ID` do hub. Uma divergência descarta cada evento sem erro. [Operando o Streaming Hub](/pt/streaming-hub/operating-streaming-hub) enuncia essa regra. ## As cinco chamadas *** ``` 1. GET /v1/catalog → o que os seus manifestos de produtor declaram 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 → uma entrega bem-sucedida ``` ## 1. Obtenha a chave de correspondência *** `GET /v1/catalog` O catálogo lista o que os manifestos de produtor em `STREAMING_HUB_MANIFEST_SOURCES` declaram. Cada entrada dá um `eventType` e um `topic`. **O catálogo não carrega a chave de correspondência.** `eventType` é apenas o segmento de evento. O `topic` dobra o nome do serviço do produtor no segmento de recurso. Então `lerian.streaming.ledger_organization.created` tem `eventType` `created`, e a chave que você precisa é `organization.created`. Pegue a chave nas páginas por produto em [Streaming de eventos](/pt/reference/events/overview). O próprio `/streaming/manifest` do produtor também reporta `resourceType` ao lado de `eventType`. O hub aceita qualquer chave bem formada em `event_types`. Uma chave que nenhum produtor emite não casa com nada, e a assinatura não recebe evento nenhum. ## 2. Crie a assinatura *** `POST /v1/subscriptions` Envie o cabeçalho `X-Idempotency` com um valor único. O hub rejeita um create que o omite, antes de qualquer gravação. ```json theme={null} { "name": "quick-start", "sink_kind": "webhook", "endpoint": "https://hooks.example.com/lerian", "event_types": ["organization.created"] } ``` `event_types` guarda **chaves de match**, não tipos CloudEvents completos. Uma chave de match é a cauda `.` — `organization.created`, e nunca o tipo completo `studio.lerian.organization.created`. Envie a chave que você montou no passo 1. Omita `event_types` para receber todo evento que o hub vê. As páginas por produto em [Streaming de eventos](/pt/reference/events/overview) descrevem cada tipo em detalhe — comece pelo [catálogo de eventos do Midaz](/pt/reference/events/midaz). `plan_tier` assume `standard` por padrão. `schema_major` é opcional — deixe-o de fora para seguir a versão base. A resposta `201` traz o `id` da assinatura e o `signingSecret` em texto puro. **Salve o segredo agora.** Nenhuma rota de leitura o devolve, e se você o perder a sua única saída é a rotação. ## 3. Ative o destino *** `POST /v1/subscriptions/{id}/ping` Uma assinatura de webhook nova nasce em `pending_verification`. O hub só entrega para ela depois que uma sondagem provar que o destino responde, então **esta chamada é obrigatória**. Ela envia uma solicitação sintética e assinada pelo caminho de entrega de produção e depois reporta o resultado: ```json theme={null} { "outcome": "ok", "statusCode": 200, "errorClass": "" } ``` `outcome: "ok"` move a assinatura para `active`, que é o estado que a torna entregável. O seu endpoint precisa responder com um `2xx` para isso acontecer, então faça o deploy dele antes do ping. Uma sondagem que rodou e falhou ainda é um `200` — leia `outcome`, não o status HTTP. `outcome: "failed"` deixa a assinatura sem verificação e nomeia a causa em `errorClass`. Corrija o endpoint e repita o ping. A chamada é segura para repetir e não precisa de chave de idempotência. A entrega exige `enabled` **e** `verification_state = active`. [Gerenciando assinaturas](/pt/streaming-hub/managing-subscriptions) explica por que os dois campos ficam separados. ## 4. Dispare um evento *** Faça algo em um produto Lerian que emita o tipo que você assinou. No Midaz, criar uma organização emite o evento acima. `POST /v1/organizations` ```json theme={null} { "legalName": "Quick Start Ltda", "legalDocument": "00000000000191" } ``` O Midaz publica o evento no stream logo depois de persistir a organização. A entrega chega ao seu endpoint instantes depois, não dentro desta chamada. ## 5. Confirme a entrega *** O seu endpoint recebe um `POST` que traz o payload do evento, uma assinatura HMAC e os cabeçalhos de contexto do hub, entre eles `X-Lerian-Event-Id`, `X-Lerian-Event-Type` e `X-Lerian-Delivery-Id`. Verifique a assinatura antes de confiar no corpo: uma solicitação sem verificação não prova nada. [Consumindo eventos](/pt/streaming-hub/consuming-events) tem os passos de verificação, a lista completa de cabeçalhos e a regra de deduplicação. Depois pergunte ao hub o que ele registrou. `GET /v1/subscriptions/{id}/health` | Campo | O que ele diz | | -------------------- | -------------------------------------------------------- | | `verification_state` | `active` depois que o ping teve sucesso. | | `status` | O veredito consolidado: `Healthy`, `Degraded` ou `Down`. | | `delivery_outcomes` | Contagens de tentativas da janela, por resultado. | | `last_success_at` | Quando a última entrega teve sucesso. | | `dead_lettered` | Tentativas que esgotaram as retentativas. | Um sucesso em `delivery_outcomes` e um `last_success_at` recente significam que o caminho funciona de ponta a ponta. Se nada chegou, `status` e `delivery_outcomes` dizem se o hub tentou e falhou, ou se nunca deu match no evento. ## Prefere usar pull? *** Uma assinatura `pull` não precisa de endpoint nem de sondagem. Crie-a com `sink_kind: "pull"` e sem `endpoint` — o hub sintetiza um, e a assinatura nasce `active`. Leia páginas de eventos com `GET /v1/events?subscription_id=`. A leitura é o reconhecimento, então leia as regras do cursor em [Consumindo eventos](/pt/streaming-hub/consuming-events) antes da sua primeira chamada. ## Próximos passos *** Sinks de fila, grants delegados da AWS, rotação de segredos e recuperação. Verifique assinaturas, deduplique entregas e use pull com cursor. Match, despacho, a curva de retentativas e o auto-disable. Faça o deploy do hub, configure-o e observe-o funcionando.