Subscribers

Os subscritores (subscribers) são as aplicações ou parceiros que recebem os eventos distribuídos pelo Events Hub.

Para receber os eventos, os subscritores devem ser conectados aos tópicos, que são agrupados dentro dos handlers. Cada tópico pode ter diferentes contextos disponíveis para o subscritor. Portanto, quando os eventos são enviados para um tópico com definição de contexto, apenas os subscritores do tópico com aquele contexto habilitado receberão os eventos.

O Events Hub cuida de toda a segurança, garantindo aos subscritores uma fonte de mensagens confiável.

A tela Subscribers lista todos os subscritores cadastrados e permite criar novos:

subscriber screen

Você pode buscar um subscritor específico usando os filtros do topo da página. Eles permitem pesquisar por:

  • nome do subscritor;

  • e-mail do desenvolvedor responsável;

  • nome do handler;

  • data inicial e final de criação;

  • status.

Use o campo Order by para definir a ordenação da lista. Você pode escolher visualizar pela data de criação mais recente ou mais antiga, ou por ordem alfabética.

Para visualizar as informações de um subscritor específico, clique sobre o nome na listagem. Você será direcionado para a tela de Topics onde pode editar as informações do subscritor e habilitar ou desabilitar os tópicos de que recebe eventos.

topics subscriber edit

Criando subscritores

Para criar um subscritor, clique no botão +, no canto inferior direito da tela. O cadastro ocorre em quatro etapas:

etapas subscriber

Overview

Para iniciar o cadastro, preencha os campos:

  • Name: nome do subscritor, que deve ser único.

  • Status: estado, entre aprovado (approved), pendente (pending), rejeitado (rejected) ou cancelado (canceled).

  • Description: campo não obrigatório para incluir uma descrição.

  • Developer: email do desenvolvedor responsável pelo subscritor.

Security

Nessa etapa, você certifica a segurança na conexão entre subscritores e o Events Hub.

Acesse a documentação de Segurança e Chaves para entender como funciona.

Implementamos duas camadas de segurança:

Assinatura digital

Na distribuição de eventos aos subscritores, incluímos uma assinatura digital que permite que o subscritor valide a origem da requisição. Para gerar essa assinatura, você precisa enviar uma chave de conhecimento mútuo entre o Events Hub e o subscritor. Para fazer isso, siga os passos:

  1. Clique no ícone icon copy do campo Post Key URL para copiar a URL de destino.
    Se o tempo de validação expirar, clique no ícone icon refresh para gerar uma nova URL;

  2. Acesse o Postman e faça uma requisição POST com a URL copiada;

  3. No body, você deve passar a chave gerada na URL através do parâmetro:

{
    "key": "2590fb78-b8c8-4dde-905f-5169ab1cf531"
}
O código da chave está na URL entre uris e key, como neste exemplo: key example.

Se o envio for bem-sucedido, você verá a mensagem Post key URL validated url validated na tela de Security.

Se cadastrar um subscritor sem o envio da chave de conhecimento mútuo, não será possível vinculá-lo a nenhum tópico.
Você só poderá fazer isso após enviar a chave, seguindo os passos descritos acima.

Token estático ou dinâmico

Após enviar a chave de conhecimento mútuo, você pode também incluir um token estático ou dinâmico para ser trafegado nas requisições aos subscritores.

token registration
A configuração de tokens não é obrigatória. Entenda como funcionam e quais as diferenças entre estático e dinâmico na documentação de Tokens.

Para configurar um token, siga os passos:

  1. Clique no botão CONFIGURE TOKEN;

  2. Selecione o tipo entre Static e Dynamic;

  3. No campo Location, selecione onde o token deve ser passado na requisição. As opções são header ou query param;

  4. No campo Name, informe o nome com o qual o valor do token será passado;

  5. A depender de qual tipo de token você selecionou, configure:

    1. Token SHA-256: valor do token. Você pode gerar um token randômico pelo ícone icon token.
      Após salvar, o token será exibido apenas uma vez em uma janela modal. Copie-o e salve-o em um arquivo no seu computador.

    2. URL OAuth: URL de geração do valor do token.
      Após salvar, será enviada uma requisição para a URL do subscritor para gerar o token e validar a configuração.

Acesse a documentação e confira os detalhes da requisição enviada e a resposta esperada.

Se algum token for configurado, a tela mostrará seus detalhes:

token post validate
Você pode configurar apenas um token por subscritor.

Topics

Na aba TOPICS, você vincula o subscritor aos tópicos de que receberá eventos. Os tópicos cadastrados são exibidos por meio dos handlers.

  • Você pode procurar por handlers específicos usando o campo Keywords, que procura por termos usados no nome ou descrição do handler. Além disso, pode reordenar a lista por nome ou data de criação através do campo Order by.

Para vincular tópicos ao seu subscritor, siga os passos:

  1. Ao escolher um handler, clique no ícone icon view topics da coluna View Topics;

  2. Na tela que abrir, clique no ícone icon expand e habilite também o contexto para o subscritor;

  3. No campo Subscriber URL, informe a URL que receberá os eventos;

  4. No campo Status Code, informe o código de estado de sucesso que deverá retornar. Esse campo permite apenas códigos de 200 a 299. Você pode inserir 2xx para abranger toda a família.

O Events Hub fará uma requisição para validar a URL esperando o código informado.

Se a URL não for validada, o subscritor será cadastrado, mas não receberá eventos.

Ao enviar eventos para o subscriber, o Events Hub levará em conta o código que você definiu como sucesso no campo Status Code. Se você informar o código 204 e retornar 200, o sistema entenderá que houve falha na entrega e enviará o evento para a fila de Delivery Retry. Para evitar isso, informe 2xx no campo de Status Code. Assim, qualquer código da família 200 será interpretado como sucesso.

add topic subscriber

Cada tópico selecionado será listado na seção SUBSCRIBED TOPICS. Para remover o vínculo, clique no ícone icon delete.

A coluna STATUS indica se a URL foi validada com sucesso ou não. O ícone verde representa sucesso. O ícone cinza significa que a URL foi cadastrada, mas a validação falhou.

subscriber enabled subscripition

Review

A etapa final de registro de um subscritor exibe os dados cadastrados:

review subscriber

Thanks for your feedback!
EDIT
How useful was this article to you?