Pular para o conteúdo principal
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).

​
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:

​
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 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 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 (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 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 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:
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.

​
Próximos passos

Consumindo eventos

Verifique assinaturas de webhook, deduplique entregas e consuma eventos por pull.

Como o Streaming Hub funciona

Match, despacho, retentativas e desativação automática em detalhe.