Skip to main content
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 — chaves <resource>.<event> sem a fonte que devem ser entregues. 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 dá match. Pegue cada chave nas páginas por produto em Streaming de eventos.
  • origin — um pin opcional que deve ser exatamente igual a ce-source. Omita-o para aceitar a mesma chave de qualquer aplicação produtora.
  • 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:
A entrega por fila não preserva o ce-type canônico com source. SQS e RabbitMQ definem ce-type como a chave simples <resource>.<event>; o EventBridge usa essa chave em DetailType e Detail.type, e seu source identifica o hub, não o produtor. Fixe origin e mantenha a identidade da assinatura junto da entrega quando a identidade do produtor for relevante.

​
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 não precisa de credencial, apenas de uma sondagem:
  1. Create — POST /v1/subscriptions com sink_kind: "webhook" e seu endpoint https://. Envie o cabeçalho X-Idempotency com um valor único: o hub rejeita um create que o omite, antes de qualquer gravação. 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 em pending_verification, 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. Ative o destino — POST /v1/subscriptions/:id/ping envia uma sondagem sintética e assinada pelo caminho real de entrega e reporta o resultado classificado. Uma sondagem bem-sucedida move a assinatura para active, e é isso que a torna entregável. Faça o deploy do seu endpoint antes do ping: ele precisa responder 2xx.
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 que a sondagem tem sucesso, a assinatura de webhook passa pelo match e começa a receber eventos. Para o passo a passo completo, do create até uma primeira entrega confirmada, veja o início rápido. 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 — forneça uma credencial de saída, verificada na escrita (abaixo), ou conecte um grant delegado da AWS (próxima seção) sem armazenar uma credencial.
Para qualquer tipo de fila, o fluxo de credencial de saída 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). Envie o cabeçalho X-Idempotency com um valor único, como em qualquer create. 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 de saída. O hub a mantém em memória, a sonda imediatamente (conecta e autentica contra o destino), e a persiste como texto cifrado somente se a sondagem tiver sucesso — uma sondagem que falha não armazena nada. Os endereços de destino são validados contra faixas bloqueadas antes do armazenamento. 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 o caminho AWS sem credenciais (sqs, eventbridge), o hub entrega assumindo uma role na sua conta AWS. Você conecta essa confiança em vez de fornecer uma credencial de saída:
  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), para que você nunca acredite que uma mudança proibida tenha surtido efeito. event_types e origin são imutáveis; crie uma nova assinatura quando precisar mudar um desses filtros. Alterar o endpoint, o tipo de sink ou o segredo também fica fora do escopo do PATCH. Uma refixação do major não muda o destino — ela não redefine verification_state nem expõe um 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.