> ## 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. # Gerenciando assinaturas > Crie assinaturas de webhook e de fila no Streaming Hub, conecte um grant delegado da AWS, rotacione um segredo de assinatura, recupere um destino desativado automaticamente e refixe um schema major. Uma **assinatura** informa ao Streaming Hub quais eventos vão para qual destino do seu tenant. Você gerencia as assinaturas através da API de control-plane `/v1`, autenticada com um JWT do plugin-auth. Esta página cobre o modelo e os fluxos de onboarding; os formatos exatos de requisição e resposta estão na referência da API (comece pela [introdução da referência](/pt/reference/introduction)). ## O modelo de assinatura *** Uma assinatura registra: * **`name`** — um rótulo legível (obrigatório, não vazio). * **`sink_kind`** — um entre `webhook`, `pull`, `sqs`, `rabbitmq`, `eventbridge`. * **`endpoint`** — para onde as entregas vão, em um formato que depende do tipo de sink (veja abaixo). * **`event_types`** — os tipos de evento a entregar. Um tipo desconhecido gera um aviso, mas nunca bloqueia um create, então uma lacuna no catálogo nunca trava o onboarding. * **`schema_major`** — a versão major do payload que a assinatura segue. * **`plan_tier`** — o tier de entrega sob o qual a assinatura roda. O formato do endpoint segue o tipo de sink: | Tipo de sink | Endpoint | | ------------- | -------------------------------------------------------------------------------------------------------------------------- | | `webhook` | Uma URL `https://`, sem userinfo embutida. | | `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` | A string de endereçamento nome do event bus / detail-type. A região fica na credencial criptografada. | ### Dois campos de status ortogonais *** Toda assinatura carrega dois campos de status independentes. Confundi-los é a fonte mais comum de perguntas do tipo "por que a entrega parou", então mantenha-os separados: * **`verification_state`** é a **prova** de que o destino consegue de fato receber eventos. Ele se move por `pending_verification` → `active` → `degraded`, guiado por sondagens. Somente uma assinatura `active` é entregável. * **`enabled`** é a **chave de entregabilidade**. É o que a desativação automática desliga, e o que um re-enable liga de novo. O match de assinaturas exige **ambos**: uma assinatura só entrega quando `enabled` **e** `verification_state = active`. A desativação automática vive inteiramente em `enabled` e nunca muda `verification_state`, então uma assinatura desativada automaticamente aparece como `enabled = false, verification_state = active`. Veja [desativando automaticamente um destino quebrado](/pt/streaming-hub/how-streaming-hub-works) para como os dois interagem. ## Criando uma assinatura de webhook *** Uma assinatura de webhook é a mais simples de fazer o onboarding — ela nasce pronta para receber: 1. **Create** — `POST /v1/subscriptions` com `sink_kind: "webhook"` e seu endpoint `https://`. A URL de destino é validada contra faixas de endereço privadas, de loopback e de metadados de nuvem antes de qualquer linha ser gravada, de modo que um alvo privado ou de metadados nunca possa ser armazenado. A resposta retorna a nova assinatura **já `active`**, e o **segredo de assinatura exatamente uma vez**. 2. **Salve o segredo de assinatura** — ele é mostrado apenas nesta resposta, armazenado apenas como texto cifrado e nunca retornado por nenhuma leitura. Salve-o ao recebê-lo; se você o perder, só é possível rotacionar para um novo. 3. **Confirme a acessibilidade (opcional)** — `POST /v1/subscriptions/:id/ping` envia uma sondagem sintética e assinada pelo caminho real de entrega e reporta o resultado classificado. O segredo de assinatura é retornado apenas na resposta do create (e novamente na rotação). Ele nunca é logado, nunca armazenado em texto puro e nunca retornado por um `GET`. Capture-o quando criar a assinatura. Uma vez criada, a assinatura de webhook passa pelo match e começa a receber eventos. Veja [Consumindo eventos](/pt/streaming-hub/consuming-events) para saber como verificar a assinatura em cada entrega. ## Fazendo o onboarding de uma assinatura de fila *** As assinaturas de fila (`sqs`, `rabbitmq`, `eventbridge`) nascem **`pending_verification`** e **não entregam nada** até que seu destino seja verificado. Como você verifica depende do tipo: * **RabbitMQ** — forneça uma credencial de broker, verificada na escrita (abaixo). * **SQS e EventBridge** — [conecte um grant delegado da AWS](#conectando-um-grant-delegado-da-aws) (próxima seção) em vez de armazenar uma credencial. Para o RabbitMQ, o fluxo de credencial tem três passos: 1. **Create** — `POST /v1/subscriptions` com o `sink_kind` da fila e seu endpoint, e **nenhuma** credencial inline (um `sink_config` ou `credential` inline é rejeitado). A assinatura é armazenada como `pending_verification`; o match 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 write-only do broker. O hub a mantém em memória, **a sonda imediatamente** (conecta e autentica contra o broker), e a persiste como texto cifrado **somente se a sondagem tiver sucesso** — uma sondagem que falha não armazena nada. O host do broker é validado contra faixas de endereço bloqueadas antes de ser armazenado. Uma sondagem bem-sucedida vira a assinatura de `pending_verification → active` na mesma transação. 3. **Active** — uma vez `active`, o match admite a assinatura e ela começa a receber eventos. A credencial é **write-only**: você a fornece aqui e ela nunca é retornada, nem mesmo mascarada, em nenhum caminho de leitura. Para trocá-la, faça `PUT` de uma nova — a mesma sondagem-na-escrita se aplica. ## Conectando um grant delegado da AWS *** Para sinks da AWS (`sqs`, `eventbridge`), o hub entrega assumindo uma role **na sua conta AWS** — ele nunca armazena uma credencial AWS. Você conecta essa confiança antes de fornecer a credencial: 1. **Busque os artefatos de setup** — `GET /v1/subscriptions/:id/setup-artifacts` retorna uma **trust policy** IAM cross-account, um **link de criação rápida** do CloudFormation e um **`ExternalId`** não secreto que o hub cunha para esta assinatura. 2. **Aplique-os na sua conta AWS** — crie a role de entrega a partir da trust policy (o link de criação rápida a monta). A role confia no principal do hub *somente* sob a condição do `ExternalId` cunhado, o que fecha a brecha de confused-deputy: uma trust policy sem essa condição é tratada como falha de verificação, nunca como verificada. 3. **Registre o grant** — `PUT /v1/subscriptions/:id/delegated-grant` com o ARN da role de entrega, a região e o destino. Isso registra apenas coordenadas não secretas; não roda sondagem alguma e não muda `verification_state`. 4. **Verify** — `POST /v1/subscriptions/:id/verify` roda a sondagem endurecida de assunção de role e, em caso de sucesso, vira a assinatura para `active`. Nenhuma credencial AWS jamais atravessa essas requisições nem é armazenada pelo hub; o hub assume a sua role a cada entrega, protegido pelo `ExternalId`. ## Rotacionando um segredo de assinatura *** `POST /v1/subscriptions/:id/secret/rotate` cunha um **novo** segredo de assinatura de webhook, o retorna **uma vez** e inicia uma **sobreposição de assinatura dupla de 24 horas**. Durante a sobreposição, o hub assina cada entrega com **ambos** os segredos — o novo e o anterior — e envia **dois** cabeçalhos de assinatura, para que o seu consumidor possa migrar para o novo segredo em qualquer ponto da janela sem perder entregas. Rotacione de forma limpa assim: 1. Chame o rotate e salve o novo segredo da resposta (junto com o timestamp `overlapUntil`). 2. Faça o deploy do novo segredo no seu consumidor dentro da janela de sobreposição. Enquanto os dois estiverem configurados, o seu verificador aceita uma entrega se **qualquer uma** das assinaturas validar. 3. Depois da sobreposição, aposente o segredo antigo. Rotacionar um sink `pull` — que não tem segredo de assinatura — é rejeitado. Veja [lidando com duas assinaturas durante a rotação](/pt/streaming-hub/consuming-events) para a verificação do lado do consumidor. ## Recuperando uma assinatura desativada automaticamente *** Quando um destino permanece quebrado por tempo suficiente, o hub [desativa automaticamente](/pt/streaming-hub/how-streaming-hub-works) a assinatura virando `enabled = false`. Para recuperá-la: 1. Conserte o destino (o endpoint, a fila ou o grant). 2. Chame `POST /v1/subscriptions/:id/verify`. Ele re-sonda o destino e, em uma sondagem bem-sucedida, reabilita a assinatura e limpa a marca de desativação automática — no lugar, mantendo o mesmo id e o mesmo segredo de assinatura. Uma re-sondagem que falha não muda nada, então o re-enable está sempre atrelado a um sucesso de sondagem real e atual. `GET /v1/subscriptions/:id/health` fornece o resumo de saúde de entrega — resultados recentes, contagens de dead-letter e o veredicto de desativação automática — para você confirmar que o destino está saudável antes e depois. ## Refixando o schema major *** `PATCH /v1/subscriptions/:id` refixa o `schema_major` da assinatura — o **único** campo mutável: * `{"schema_major": 2}` fixa a assinatura naquela versão major. * `{"schema_major": null}` limpa a fixação para seguir a versão base. Qualquer outro campo, um corpo vazio ou um valor abaixo de `1` é **rejeitado** (não silenciosamente ignorado), de modo que você nunca acredite que uma mudança proibida tenha surtido efeito. Mudar o endpoint, o tipo de sink ou o segredo está fora do escopo do `PATCH` por design; crie uma nova assinatura para um destino diferente. Uma refixação não é uma mudança de destino — ela não reseta `verification_state` e não ecoa nenhum segredo. ## Idempotência *** As rotas mutáveis — create, delete, `PATCH`, secret rotate e registro de grant delegado — exigem uma chave de idempotência: ``` X-Idempotency: ``` Uma mutação enviada sem ela é rejeitada **antes de qualquer gravação** com `400 missing_idempotency_key`. O store é **fail-closed**: se o store de idempotência estiver inacessível, a requisição falha em vez de arriscar uma gravação dupla — isso garante que um create ou rotate reexecutado sirva de novo o segredo original mostrado uma única vez, em vez de cunhar um novo. * Reexecutar uma chave já confirmada retorna a resposta original byte a byte, com `X-Idempotency-Replayed: true`. * Reutilizar uma chave com um corpo de requisição *diferente* retorna `409 idempotency_conflict` — cunhe uma nova chave para uma requisição corrigida. As rotas de verificação (`ping`, `verify`, `PUT /credential`, `GET /setup-artifacts`) são naturalmente idempotentes e não exigem chave. Veja a orientação de toda a plataforma sobre [retentativas e idempotência](/pt/reference/retries-idempotency). ## Próximos passos *** Verifique assinaturas de webhook, deduplique entregas e consuma eventos por pull. Match, despacho, retentativas e desativação automática em detalhe.