Tecnologia | Senior X - Manual do Usuário > Customização > Events Hub

Events Hub

O Events Hub é a aplicação responsável por administrar Webhooks na plataforma Senior. Um Webhook conecta um evento de negócio (gerado por um domínio ou serviço da plataforma) a um ou mais endpoints externos (URLs), de forma que, sempre que o evento acontece, o Events Hub notifica automaticamente esses endpoints com os dados do evento.

Por meio da aplicação, você pode cadastrar, consultar, editar e monitorar Webhooks, configurar a autenticação e a assinatura das requisições enviadas, além de acompanhar o histórico de entregas e reenviar eventos que falharam.

Principais capacidades:

Cadastrar Webhooks associando um evento a endpoints de destino;
Configurar autenticação básica, autenticação avançada e assinatura HMAC por endpoint;
Testar a conexão com o endpoint antes de salvar;
Acompanhar o histórico de envios;
Reenviar eventos que não foram entregues com sucesso.

Acesse Tecnologia > Customização > Events hub > Webhooks.

Conceitos principais

Evento: combinação de domínio, serviço e primitiva que representa um acontecimento de negócio na plataforma;
Webhook: vínculo entre um evento e a lista de endpoints que devem ser notificados quando o evento ocorrer;
Endpoint: URL de destino que recebe a notificação (requisição HTTP) com os dados do evento;
Payload Filter (JsonPath): expressão JsonPath usada para filtrar e selecionar quais dados do evento serão enviados ao endpoint;
Histórico: registro de cada tentativa de envio, com status HTTP, duração, bytes trafegados e conteúdo enviado e recebido.

Permissões de acesso

O acesso às funcionalidades é controlado por permissões da plataforma. O Events Hub trabalha com dois recursos de permissão distintos:

webhook (Visualizar, Editar): controla o acesso à listagem, ao cadastro e à edição de Webhooks e à visualização do histórico;
hmac (Editar): permissão específica para configurar a assinatura HMAC de um endpoint, independente da permissão do Webhook.

Sem a permissão de Visualizar, o sistema exibe a mensagem Não é permitido visualizar e não carrega os registros. A permissão de Editar é necessária para cadastrar novos Webhooks e alterar os existentes.

Listagem de Webhooks

É a tela inicial do Events Hub. Apresenta todos os Webhooks cadastrados em formato de grade, com paginação e busca. As colunas exibidas são:

Domínio / Serviço / Primitiva: identificação do evento associado ao Webhook;
Ações: menu de ações disponíveis para cada registro.

Recursos disponíveis na tela:

Campo de busca: filtra os Webhooks pelo termo digitado;
Novo: abre a tela de cadastro de um novo Webhook;
Ações > Detalhes: abre a tela de histórico de envios do Webhook selecionado;
Ações > Editar: abre o Webhook selecionado para edição.

Quando nenhum Webhook é encontrado, a tela exibe a mensagem Nenhum Webhook foi encontrado. Clique no botão abaixo para adicionar.

Configuração dos endpoints

Cada Webhook pode ter vários endpoints. Ao adicionar um endpoint, os seguintes campos e opções ficam disponíveis:

URL: endereço de destino que receberá a notificação. Campo obrigatório;
Payload Filter (JsonPath): expressão JsonPath para filtrar os dados enviados ao endpoint;
Cabeçalhos HTTP (Headers): pares chave/valor enviados em cada requisição. Há um limite total de 3800 caracteres somando todos os headers;
Basic Auth: usuário e senha para autenticação básica na chamada ao endpoint;
Habilitar Retry: habilita as tentativas de reenvio;
Códigos HTTP a ignorar: códigos HTTP (entre 100 e 599) que não acionam novas tentativas de reenvio;
Tipo de envio: define como as mensagens são processadas, sendo Processamento sequencial ou Paralelo.

Autenticação avançada

Além da autenticação básica (usuário e senha), o endpoint pode utilizar a autenticação avançada. Ao habilitar essa opção por meio do toggle de autenticação avançada, é possível configurar um fluxo de autenticação personalizado, com os seguintes recursos:

Autenticação Interna: quando marcada, o sistema utiliza a autenticação interna da Senior para validar o endpoint;
Headers: cabeçalhos enviados na requisição de autenticação;
Payload: parâmetros do corpo da requisição de autenticação;
Payload Filters: filtros do corpo da resposta, com as chaves TOKEN, VALID_FOR_SECONDS e REFRESH_TOKEN;
Refresh Token: URL e payload usados para renovar o token de acesso.

Assinatura HMAC

A assinatura HMAC garante a integridade e a autenticidade das requisições enviadas ao endpoint. Quando habilitada, cada requisição recebe os cabeçalhos X-Webhook-Timestamp e X-Webhook-Signature, assinados com a chave configurada.

A configuração de HMAC só fica disponível para endpoints já salvos (persistidos) no Webhook;
A configuração é protegida pela permissão específica do recurso hmac;
A chave deve ter no mínimo 32 caracteres. Se o campo for deixado em branco, o sistema gera uma chave automaticamente;
A chave é exibida uma única vez, ao concluir a configuração. Por segurança, ela não é mostrada novamente;
Reconfigurar o HMAC em um endpoint que já possui chave substitui a chave anterior (rotação). Os consumidores precisam ser atualizados com a nova chave.

Histórico de envios

A tela de histórico registra cada tentativa de envio do Webhook, permitindo o monitoramento das entregas. Ela é acessada pela ação Detalhes na listagem de Webhooks. As colunas exibidas são:

Http Status: código HTTP retornado pelo endpoint;
URL: endereço de destino da requisição;
Início: data e hora do envio;
Duração (ms): tempo de resposta em milissegundos;
Enviados/Recebidos (Bytes): volume de dados trafegado;
Ações: opção de reenviar o evento.

Recursos de filtro e consulta:

Período: seleção de intervalo de datas ou de períodos pré-definidos (Minuto, Hora, Dia, Semana e Mês);
Termo: busca por um texto específico dentro dos registros;
Somente Erros: exibe apenas os envios com erro;
Detalhes da Requisição: ao expandir um registro, é possível visualizar os detalhes da requisição, incluindo o conteúdo enviado e recebido.

PORTAL DE DOCUMENTAÇÃO
Tecnologia \| Senior X