Skip to main content
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).

​
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 <resource>.<event> 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.
  • 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:
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 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 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. Veja Consumir eventos 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 (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 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 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:
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.

​
Próximos passos

Consumir eventos

Verifique assinaturas de webhook, deduplique entregas e puxe eventos.

Como o Streaming Hub funciona

Correspondência, despacho, novas tentativas e desabilitação automática em detalhe.