Skip to main content
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 <token> 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 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.
  • 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. 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 enuncia essa regra.

​
As cinco chamadas

​
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. 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.
event_types guarda chaves de match, não tipos CloudEvents completos. Uma chave de match é a cauda <recurso>.<evento> — 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 descrevem cada tipo em detalhe — comece pelo catálogo de eventos do 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:
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 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
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 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 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=<id>. A leitura é o reconhecimento, então leia as regras do cursor em Consumindo eventos antes da sua primeira chamada.

​
Próximos passos

Gerenciando assinaturas

Sinks de fila, grants delegados da AWS, rotação de segredos e recuperação.

Consumindo eventos

Verifique assinaturas, deduplique entregas e use pull com cursor.

Como o Streaming Hub funciona

Match, despacho, a curva de retentativas e o auto-disable.

Operando o Streaming Hub

Faça o deploy do hub, configure-o e observe-o funcionando.