> ## 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 token do Access Manager. 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](https://docs.lerian.studio/pt/reference/introduction.md)).

## O modelo de subscription

***

Uma subscription registra:

* **`name`**: um rótulo legível (obrigatório, não vazio). Se uma subscription não excluída já tem o nome, a criação devolve `409 subscription_name_taken`.
* **`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`**: as chaves a entregar. Pegue cada chave do campo `eventKey` de `GET /v1/catalog`, exatamente como servida. O hub recusa uma chave que o catálogo não lista no schema major em que a subscription a recebe, com `422 unknown_event_type`. Quando `origin` está definido, a entrada do catálogo precisa vir desse produtor. Quando o catálogo não pode ser lido ou ainda não lista nenhum evento de produtor, o hub aceita as chaves sem checar. Omita o campo para receber todos os tipos de evento.
* **`schema_major`**: a versão major do payload que a subscription segue. Omita-o para seguir a versão major 1.
* **`event_majors`**: um mapa opcional de tipo de evento para schema major, por exemplo `{"loan_application.disbursed": 2}`. Ele substitui o `schema_major` para os tipos que nomeia. Quando `event_types` lista tipos, cada chave precisa ser um deles.
* **`timeout_ms`**: apenas para um webhook, o timeout de entrega por tentativa, de 1000 a 20000 milissegundos. O padrão é 10000.
* **`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://<id>`. |
| `sqs` | A URL `https://` da fila SQS. |
| `rabbitmq` | `<exchange>/<routingKey>` (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. |

> [!WARNING]
>
> 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 `<resource>.<event>` 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 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](https://docs.lerian.studio/pt/platform/streaming-hub/how-streaming-hub-works.md) 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. Se a consulta DNS do próprio hub falhar ou expirar, ele responde `503 dns_unavailable` ou `504 dns_timeout` e não grava nada: tente de novo com a mesma chave. A resposta devolve a nova subscription em `pending_verification` e o signing secret.
2. **Guarde o signing secret**: nenhuma rota de leitura o devolve. Uma nova tentativa com a mesma chave `X-Idempotency` devolve a mesma resposta. O hub guarda o segredo apenas como texto cifrado. 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. Uma sondagem que falha traz um `detail` que diz por que falhou. Faça o deploy do seu endpoint antes do ping: ele deve responder `2xx`.

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](https://docs.lerian.studio/pt/platform/streaming-hub/streaming-hub-quick-start.md). Veja [Consumir eventos](https://docs.lerian.studio/pt/platform/streaming-hub/consuming-events.md) 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 move a subscription para `active`.
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. O hub chega à sua conta assumindo o seu papel sob o `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 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.

Apenas uma subscription de webhook tem signing secret. O hub rejeita a rotação para cada outro tipo de sink. Veja [tratar duas assinaturas durante a rotação](https://docs.lerian.studio/pt/platform/streaming-hub/consuming-events.md) 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](https://docs.lerian.studio/pt/platform/streaming-hub/how-streaming-hub-works.md) 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 reabilita a subscription, e move um estado de verificação `active` para `degraded`. 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. As contagens dele cobrem o intervalo de `window_start` a `snapshot_at`. Limites iguais significam que o hub não guarda histórico de entrega, não que a entrega está saudável.

## Mudar a fixação do schema e o timeout

***

O `PATCH /v1/subscriptions/:id` muda dois campos. Todo corpo deve trazer `schema_major`:

* `{"schema_major": 2}` fixa a subscription naquela versão major.
* `{"schema_major": null}` limpa a fixação, então a subscription segue a versão major 1.
* Em um webhook, adicione `"timeout_ms"` para mudar o timeout por tentativa, ou envie `0` para voltar ao padrão de 10000. Envie o `schema_major` atual junto para manter a fixação.

O hub rejeita qualquer outro campo, um corpo sem `schema_major` ou um `schema_major` abaixo de `1`. Ele nunca os ignora em silêncio, então você nunca pode acreditar que uma mudança proibida teve efeito. Ele também responde `422 unknown_event_type` quando o novo pin deixa um tipo de evento guardado sem entrada no catálogo no major dele. Os campos `event_types`, `event_majors` e `origin` são imutáveis. Crie uma nova subscription quando um deles precisar mudar.

Um `PATCH` nunca muda o endpoint, o tipo de sink ou o segredo. Ele 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: <your-unique-key>
```

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 devolva o segredo original em vez de cunhar um novo.

* Repetir uma chave já confirmada dentro da janela de retenção (24 horas por padrão) devolve a resposta original byte a byte, com `X-Idempotency-Replayed: true`.
* Reusar uma chave enquanto a primeira requisição ainda roda, ou com um corpo de requisição *diferente*, devolve `409 idempotency_conflict`. Cunhe uma chave nova para uma requisição corrigida.
* Uma mutação que pode ter sido confirmada sem resultado registrado responde `500 idempotency_outcome_unrecorded`. Um envio posterior com essa chave pode responder `409 idempotency_outcome_unrecorded`. Leia o recurso antes de enviar qualquer coisa de novo.

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](https://docs.lerian.studio/pt/reference/retries-idempotency.md).

## Próximos passos

***

> [card] [Consumir eventos](https://docs.lerian.studio/pt/platform/streaming-hub/consuming-events.md)
>
> Verifique assinaturas de webhook, deduplique entregas e puxe eventos.

> [card] [Como o Streaming Hub funciona](https://docs.lerian.studio/pt/platform/streaming-hub/how-streaming-hub-works.md)
>
> Correspondência, despacho, novas tentativas e desabilitação automática em detalhe.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.