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

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

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