> ## 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. # Gerenciar subscriptions > Crie subscriptions de webhook e de fila no Streaming Hub, monte uma concessão delegada da AWS, faça a rotação de signing secrets, recupere destinos desabilitados e refixe. Uma **subscription** diz ao Streaming Hub quais eventos vão para qual destino no seu tenant. Você gerencia subscriptions pela API de control plane `/v1`, autenticada com um JWT do plugin-auth. Esta página cobre o modelo e os fluxos de onboarding. A referência da API tem os formatos exatos de requisição e resposta (comece pela [introdução da referência](/pt/reference/introduction)). ## O modelo de subscription *** Uma subscription registra: * **`name`**: um rótulo legível (obrigatório, não vazio). * **`sink_kind`**: um entre `webhook`, `pull`, `sqs`, `rabbitmq`, `eventbridge`. * **`endpoint`**: para onde vão as entregas, em um formato que depende do tipo de sink (veja abaixo). * **`event_types`**: chaves `.` livres de origem a entregar. O hub aceita qualquer chave bem formada, então uma lacuna no catálogo nunca trava o onboarding. Uma chave que nenhum produtor emite não corresponde a nada. Pegue cada chave nas páginas por produto em [Streaming de eventos](/pt/reference/events/overview). * **`origin`**: uma fixação exata e opcional de `ce-source`. Omita para aceitar a mesma chave de qualquer aplicação produtora. * **`schema_major`**: a versão major do payload que a subscription segue. * **`plan_tier`**: o nível de entrega em que a subscription roda. O formato do endpoint segue o tipo de sink: | Tipo de sink | Endpoint | | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | `webhook` | Uma URL `https://`, sem userinfo embutido. | | `pull` | Omitido — o servidor sintetiza `pull://`. | | `sqs` | A URL `https://` da fila SQS. | | `rabbitmq` | `/` (exchange obrigatório, routing key opcional). O host do broker fica na credencial criptografada. | | `eventbridge` | O nome do event bus do EventBridge. O `DetailType` é derivado do tipo de evento correspondente. A região fica na credencial criptografada. | A entrega em fila não preserva o `ce-type` canônico qualificado pela origem. SQS e RabbitMQ definem o `ce-type` como a chave `.` pura. O EventBridge usa essa chave pura no `DetailType` e no `Detail.type`, e o `source` dele identifica o hub em vez do produtor. Fixe `origin` e guarde a identidade da subscription junto da entrega quando a identidade do produtor importa. ### Dois campos de status ortogonais *** Cada subscription carrega dois campos de status independentes. Confundi-los é a fonte mais comum das perguntas "por que a entrega parou", então mantenha os dois separados: * **`verification_state`** é a **prova** de que o destino consegue mesmo receber eventos. Ele passa por `pending_verification` → `active` → `degraded`, guiado por sondagens. Apenas uma subscription `active` é entregável. * **`enabled`** é a **chave de entregabilidade**. É o que a desabilitação automática desliga, e o que uma reabilitação liga de volta. A correspondência de subscriptions exige **os dois**: uma subscription entrega apenas quando está `enabled` **e** em `verification_state = active`. A desabilitação automática vive inteiramente no `enabled` e nunca muda o `verification_state`, então uma subscription desabilitada automaticamente aparece como `enabled = false, verification_state = active`. Veja [desabilitar automaticamente um destino quebrado](/pt/platform/streaming-hub/how-streaming-hub-works) para saber como os dois interagem. ## Criar uma subscription de webhook *** Uma subscription de webhook é a mais simples de colocar no ar. Ela não precisa de credencial, apenas de uma sondagem: 1. **Crie**: `POST /v1/subscriptions` com `sink_kind: "webhook"` e seu endpoint `https://`. Envie um header `X-Idempotency` único: o hub rejeita uma criação que o omite, antes de qualquer escrita. O hub valida a URL de destino contra faixas de endereço privadas, de loopback e de metadados de nuvem antes de qualquer escrita. Ele nunca guarda um alvo privado ou de metadados. A resposta devolve a nova subscription em **`pending_verification`** e o **signing secret exatamente uma vez**. 2. **Guarde o signing secret**: apenas essa resposta o mostra. O hub o guarda apenas como texto cifrado, e nenhuma leitura o devolve. Guarde-o ao recebê-lo. Se você o perder, apenas resta fazer a rotação para um novo. 3. **Ative o destino**: `POST /v1/subscriptions/:id/ping` envia uma sondagem sintética e assinada pelo caminho real de entrega e informa o resultado classificado. Uma sondagem bem-sucedida move a subscription para `active`, e é isso que a torna entregável. Faça o deploy do seu endpoint antes do ping: ele deve responder `2xx`. O hub devolve o signing secret apenas na resposta de criação, e de novo na rotação. O hub nunca o registra em log, nunca o guarda em texto claro e nunca o devolve em um `GET`. Capture-o quando criar a subscription. Depois que a sondagem passa, a correspondência admite a subscription de webhook e ela começa a receber eventos. Para o passo a passo completo, da criação até a primeira entrega confirmada, veja o [início rápido](/pt/platform/streaming-hub/streaming-hub-quick-start). Veja [Consumir eventos](/pt/platform/streaming-hub/consuming-events) para saber como verificar a assinatura em cada entrega. ## Colocar no ar uma subscription de fila *** As subscriptions de fila (`sqs`, `rabbitmq`, `eventbridge`) nascem em **`pending_verification`** e **não entregam nada** até uma sondagem verificar o destino delas. Como você verifica depende do tipo: * **RabbitMQ**: forneça uma credencial de broker, verificada na escrita (abaixo). * **SQS e EventBridge**: forneça uma credencial de saída, verificada na escrita (abaixo), ou [monte uma concessão delegada da AWS](#wiring-an-aws-delegated-grant) (próxima seção) sem guardar credencial. Para qualquer tipo de fila, o fluxo com credencial de saída tem três passos: 1. **Crie**: `POST /v1/subscriptions` com o `sink_kind` de fila e o endpoint dele, e **nenhuma** credencial embutida (o hub rejeita um `sink_config` ou `credential` embutido). Envie um header `X-Idempotency` único, como em qualquer criação. O hub guarda a subscription em `pending_verification`. A correspondência a exclui, então ela ainda não produz jobs de entrega. 2. **Forneça a credencial**: `PUT /v1/subscriptions/:id/credential` com a credencial de saída, que é apenas de escrita. O hub a mantém em memória, **a sonda imediatamente** (conecta e autentica contra o destino) e a grava como texto cifrado **apenas se a sondagem passar**. Uma sondagem que falha não guarda nada. O hub valida os endereços de destino contra faixas bloqueadas antes da gravação. Uma sondagem bem-sucedida vira a subscription de `pending_verification → active` na mesma transação. 3. **Ativa**: uma vez `active`, a correspondência admite a subscription e ela começa a receber eventos. A credencial é **apenas de escrita**: você a fornece aqui e nenhum caminho de leitura a devolve, nem mesmo mascarada. Para trocá-la, faça um `PUT` com uma nova. Vale a mesma sondagem na escrita.

Montar uma concessão delegada da AWS

*** Para o caminho AWS sem credencial (`sqs`, `eventbridge`), o hub entrega assumindo um papel **na sua conta AWS**. Você monta essa confiança em vez de fornecer uma credencial de saída: 1. **Busque os artefatos de configuração**: `GET /v1/subscriptions/:id/setup-artifacts` devolve uma **trust policy** IAM entre contas, um **link de criação rápida** do CloudFormation e um **`ExternalId`** não secreto que o hub cunha para esta subscription. 2. **Aplique-os na sua conta AWS**: crie o papel de entrega a partir da trust policy (o link de criação rápida o monta). O papel confia no principal do hub *apenas* sob a condição do `ExternalId` cunhado. Essa condição fecha a brecha do confused deputy. Uma trust policy que a omite falha na verificação e nunca conta como verificada. 3. **Registre a concessão**: `PUT /v1/subscriptions/:id/delegated-grant` com o ARN do papel de entrega, a região e o destino. Isso registra apenas coordenadas não secretas. Não roda sondagem e não muda o `verification_state`. 4. **Verifique**: `POST /v1/subscriptions/:id/verify` roda a sondagem endurecida de assunção de papel e, em caso de sucesso, vira a subscription para `active`. Nenhuma credencial da AWS cruza essas requisições, e o hub nunca guarda uma. O hub assume o seu papel a cada entrega, protegido pelo `ExternalId`. ## Fazer a rotação de um signing secret *** O `POST /v1/subscriptions/:id/secret/rotate` cunha um **novo** signing secret de webhook, o devolve **uma vez** e começa uma **sobreposição de assinatura dupla de 24 horas**. Durante a sobreposição, o hub assina cada entrega com o segredo novo **e** com o anterior, e envia **dois** headers de assinatura. Seu consumidor pode, portanto, trocar para o segredo novo em qualquer ponto da janela sem perder entregas. Faça a rotação de forma limpa assim: 1. Chame a rotação e guarde o segredo novo da resposta (junto com o timestamp `overlapUntil`). 2. Faça o deploy do segredo novo no seu consumidor dentro da janela de sobreposição. Enquanto seu verificador tem os dois segredos, ele aceita uma entrega se **qualquer uma** das assinaturas validar. 3. Depois da sobreposição, aposente o segredo antigo. Um sink `pull` não tem signing secret, então o hub rejeita a rotação. Veja [tratar duas assinaturas durante a rotação](/pt/platform/streaming-hub/consuming-events) para a verificação do lado do consumidor. ## Recuperar uma subscription desabilitada automaticamente *** Quando um destino fica quebrado por tempo suficiente, o hub [desabilita automaticamente](/pt/platform/streaming-hub/how-streaming-hub-works) a subscription virando `enabled = false`. Para recuperá-la: 1. Corrija o destino (o endpoint, a fila ou a concessão). 2. Chame `POST /v1/subscriptions/:id/verify`. Ele sonda o destino de novo. Com uma sondagem bem-sucedida, ele reabilita a subscription e limpa a marca de desabilitação automática, no lugar e com o mesmo id e signing secret. Uma sondagem que falha não muda nada, então a reabilitação está sempre presa a um sucesso de sondagem real e atual. Chame `GET /v1/subscriptions/:id/health` para o resumo de saúde de entrega (resultados recentes, contagens de dead-letter e o veredito da desabilitação automática). Use-o para confirmar que o destino está saudável antes e depois. ## Refixar o major do schema *** O `PATCH /v1/subscriptions/:id` refixa o `schema_major` da subscription, o **único** campo mutável: * `{"schema_major": 2}` fixa a subscription naquela versão major. * `{"schema_major": null}` limpa a fixação para seguir a versão base. O hub **rejeita** qualquer outro campo, um corpo vazio ou um valor abaixo de `1`. Ele nunca os ignora em silêncio, então você nunca pode acreditar que uma mudança proibida teve efeito. Os campos `event_types` e `origin` são imutáveis. Crie uma nova subscription quando um desses filtros precisar mudar. Mudar o endpoint, o tipo de sink ou o segredo também está fora do escopo do `PATCH` por projeto. Uma refixação não é uma mudança de destino. Ela não reseta o `verification_state` e não devolve segredo algum. ## Idempotência *** As rotas que alteram estado (criação, exclusão, `PATCH`, rotação de segredo e registro de concessão delegada) exigem uma chave de idempotência: ``` X-Idempotency: ``` O hub rejeita uma alteração enviada sem ela **antes de qualquer escrita**, com `400 missing_idempotency_key`. O armazenamento **falha fechando**: se o armazenamento de idempotência estiver inacessível, a requisição falha em vez de arriscar uma escrita dupla. Isso garante que uma criação ou rotação repetida sirva de novo o segredo original mostrado uma única vez, em vez de cunhar um novo. * Repetir uma chave já confirmada devolve a resposta original byte a byte, com `X-Idempotency-Replayed: true`. * Reusar uma chave com um corpo de requisição *diferente* devolve `409 idempotency_conflict`. Cunhe uma chave nova para uma requisição corrigida. As rotas de verificação (`ping`, `verify`, `PUT /credential`, `GET /setup-artifacts`) são idempotentes por natureza e não exigem chave. Veja a orientação de toda a plataforma sobre [novas tentativas e idempotência](/pt/reference/retries-idempotency). ## Próximos passos *** Verifique assinaturas de webhook, deduplique entregas e puxe eventos. Correspondência, despacho, novas tentativas e desabilitação automática em detalhe.