Informações gerais

O serviço de notificações é parte fundamental da arquitetura baseada em eventos da PDPJ. Centralizando o processo de recebimento de eventos gerados nos serviços que compõem a plataforma e a sua entrega em forma de mensagens aos usuários e sistemas externos à PDPJ.

Veja também o webinário sobre o serviço de notificações:

Contextualização

Desde a introdução das APIs modernas, tivemos uma mudança de comportamento dos projetos elaborados em que se pensava é "bom tê-las" para uma certeza de que "devemos tê-las", especiamente para aplicações SaaS. A ideia básica da API é que quando uma aplicação precisa de um serviço ou dado específico, faz-se uma chamada à API do provedor de serviço e solicita-se o recurso específico. No entanto, as novas aplicações estão se tornando mais e mais uma composição de APIs e as arquiteturas serverless estão ganhando mais atenção, os provedores de APIs não podem se contentar apenas em prover APIs REST tradicionais. Hoje em dia os clientes precisam de aplicações mais interconectadas e que possam responder instantaniamente sem ter que fazer solicitações às APIs.

Diante deste panorama é que os webhooks tornaram-se tão desejados.

Webhooks

O que são?

"Não me chame, eu te chamo!!!". Esse é o dogma dessa solução e a promessa para seus clientes. Uma aplicação cliente não precisa fazer chamadas à API do serviço, mas o serviço fará uma chamada à API do cliente quando um certo evento ocorrer.

Vamos exemplificar o seu funcionamento, com uma situação real que acontece diariamente na relação dos escritórios de advocacia e o Poder Judiciário.

Suponha que você seja um advogado e esteja acompanhando processos de seus clientes.

No modelo tradicional, para saber o andamento dos seus processos e não perder prazos, você e seus associados precisam consultar diariamente, se não, de hora em hora, o sistema de processo judicial do tribunal correspondente para ter a informação mais recente da situação dos seus processo. Mas, os advogados têm muitos clientes e frequentemente seus processos estão em mais de um tribunal. Então, isso pode ser feito, não é? Mas, demanda muito tempo!! Ou demanda uma equipe exclusiva para isso! Fica caro! E se houvesse um serviço que pudesse dizer "Ei, eu tenho uma funcionalidade interessante de subscrição e você não precisa verificar esses processos constantemente, apenas me informar do que você precisa, deixar o seu email e eu o notificarei quando houver alguma alteração nos seus processos."

O webhook utiliza-se nesse conceito. É uma abordagem baseada em eventos que garante que o provedor do serviço possa enviar a notificação correta para o serviço externo correto no momento em que ela acontece. Em outras palavras, é um padrão arquitetural máquina-a-máquina que permite que a API do cliente receba as atualizações nos dados assim que elas acontecem, ao invés do próprio cliente ficar fazendo uma consulta constante e onerosa pelas últimas atualizações.

Os webhooks também são conhecidos como APIs reversas, já que o servidor é quem chama a API do cliente.

Por que utilizar webhook em vez de uma API?

Com as APIs, temos que buscar os dados frequentemente para obter as atualizações que precisamos. Mas essa busca frequente (polling) é muito ruim tanto para a infra-estrutura do serviço quanto para a do cliente. Há um desperdício de recursos e tempo para ambos os lados, para preparar e enviar essas requisições e para responde-las sem que contenham nada novo. Mesmo quando há uma alteração nos dados, esses dados só serão lidos e terão utilidade, quando o cliente fizer sua próxima consulta, ou seja, essa propagação da nova informação dependerá do intervalo de tempo entre as consultas, o que significa que alterações não serão entregues no mesmo instante em que acontecem.

O webhook é a única opção?

Há diversas abordagem na arquitetura baseada em eventos para notificar as aplicações clientes das alterações. Normalmente em comunicações entre sistemas internos outras opções de entrega de mensagens são mais eficientes como uma fila num serviço de mensageria ou um barramento de serviços, como é o caso da PDPJ que utiliza o serviço RabbitMQ, para comunicações entre sistemas externos a solução mais comum é a que utiliza webhooks. Veja mais sobre o Serviço de Mensageria da PDPJ-Br aqui.

Características do serviço de notificações

Ok, o serviço de notificações fornece informações às aplicações externas à PDPJ via webhooks. Mas, e quanto às pessoas que querem ser alertadas de alterações nos seus processos como elas podem fazer?

O serviço de notificações foi pensado não apenas para a comunicação máquina-a-máquina, com integrações entre sistemas externos e a PDPJ. Nós o projetamos também para que advogados, procuradores, servidores dos tribunais, magistrados e cidadãos pudessem se beneficiar da integração entre os serviços do judiciário nacional com a PDPJ.

O serviço permite que as pessoas interessadas inscrevam-se para receber notificações sempre quando algum evento com alguma determinada informação acontecer dentro da PDPJ. Por exemplo, um advogado pode solicitar que sempre que algum processo em que ele seja representante tiver algum ato de um magistrado, ele receba uma mensagem no seu Telegram.

Um representante do Ministério da Justiça pode se inscrever e solicitar que toda vez que um magistrado, em algum lugar do Brasil, promulgar uma decisão relacionada a um processo de lavagem de dinheiro, ele receba um email com as informações dessa decisão e do processo. Com isso ele pode já acionar a Polícia Federal para conseguir reaver esse dinheiro.

Uma característica importante das notificações encaminhadas por este serviço é que elas são transmitidas instantaneamente e no formato definido pelo usuário no momento da sua inscrição.

Quem pode utilizar?

Todos os usuários internos dos Tribunais autenticados no SSO da PDPJ (Serviço de Login unificado do Poder Judiciário), podem utilizar o serviço de notificações, sejam eles magistrados, servidores e/ou administradores dos sistemas dos tribunais.

Quais os meios de encaminhamento de mensagens?

O serviço de notificações permite que as mensagens sejam encaminhadas aos usuários inscritos nos seguintes protocolos:

Webhook - APIs das aplicações externas à PDPJ que receberão informações geradas dentro da PDPJ;
E-mails - endereços de e-mails de pessoas interessadas em eventos que acontecem dentro da PDPJ (em desenvolvimento);
Mensagens instantâneas - identificações de usuário do serviço de mensagens instantâneas (por exemplo: Telegram), para recebimento desses eventos.

Webhook

Ao se inscrever para recebimento de notificações com webhook, é necessário que o usuário indique um endpoint válido de um serviço acessível pela Internet e escolha um dos seguintes formatos:

RAW Neste formato o serviço de notificações enviará uma notificação ao endpoint inscrito com todos os dados originais do evento gerado pelo serviço da PDPJ, neste caso não é feito nenhum tratamento e todos os dados estarão disponíveis assim como forem gerados;
ALERTA - no formato ALERTA o serviço de notificações utilizará um template padrão para traduzir os dados originais em um formato de texto amigável com as informações mais relevantes para seu entendimento de forma simplificada e o encaminhará ao endpoint especificado pelo usuário na sua inscrição;
DOCUMENTO - este é o formato mais complexo, o seviço de notificações também utilizará de um template padrão para gerar um texto com valores do evento original, mas neste caso serão solicitadas ao usuário outras informações como "tipo de documento", "nome do documento" e "formato do documento", para que seja criado um documento no formato PDF por exemplo, assinado pelo próprio serviço e encaminhado ao endpoint em um formato padrão para que esse documento possa ser incluído diretamente em um sistema de processo eletrônico, por exemplo.

E-mail

Quando uma pessoa se inscreve para receber um e-mail toda vez que uma situação pré-definida acontecer na PDPJ, o serviço se utilizará também de um template previamente cadastrado para, a partir das informações publicadas pelo serviço, gerar um texto num formato amigável e enviá-lo para o destino informado. Basicamente, quando o usuário se utiliza desse protocolo, ele estś substituindo a funcionalidade de PUSH já existente em muitos sistema de processo judicial, com a vantagem de que o usuário inscrito no serviço de notificações poderá receber e-mails de qualquer sistema de processo eletrônico integrado à PDPJ.

Mensagens instantâneas

Ao se inscrever para recebimento de mensagens instantâneas, o usuário deverá indicar sua identificação de usuário na ferramenta correspondente (por exemplo, Telegram) e o serviço de notificações passará a encaminhar notificações resumidas dos eventos inscritos.

Como utilizar o serviço?

Interface web (front-end)

Acesso

Acesse aqui a interface do serviço em produção, que também está disponível pelo marketplace da PDPJ-Br.

O serviço se destina a duas categorias de usuários: aquela relativa aos criadores de módulos e serviços que residirão na PDPJ, os quais são responsáveis por cadastrarem no serviço os eventos negociais que poderão ser escutados, e aquela referente aos consumidores dos eventos cadastrados no serviço.

Lembrando que o objetivo do serviço de notificações é atender, além de usuários pessoas físicas em geral, os sistemas externos à nuvem da PDPJ, em particular os sistema de processo eletrônico dos Tribunais, tornando transparente para estes a existência do serviço de mensageria da PDPJ, a qual os sistemas dos Tribunais não precisam conhecer.

Nessa linha, o criador de um serviço, sistema ou módulo hospedado na PDPJ deve seguir os seguintes passos para expor ao serviços de notificações os eventos negociais relevantes que deseja serem escutados via o mencionado serviço:

Registrar o seu sistema no serviço de notificações;
Registrar os eventos/mensagens que são lançados pelo sistema;
Registrar os templates que serão utilizados para montar o documento de retorno, no caso do consumidor do evento escolher receber o vento no formato documento ou no formato alerta.

Estando o sistema e seus eventos disponíveis para consumo, o usuário consumidor, que pode ser um sistema de processo eletrônico, uma autoridade, um advogado, etc., "subscreve" o evento, registrando o modo como deseja recebê-lo (e-mail, mensagem instantânea ou webhook), e o formato de recebimento (RAW, documento ou alerta, conforme explicado acima).

Acesso

Acesse aqui o guia do usuário do Notificações ou através do menu Notificações - Guia do usuário.

API do serviço

A utilização do Serviço de Notificações deverá ser realizada preferencialmente por meio da Interface Web.

Exemplo de objeto JSON entregue no formato DOCUMENTO

{
  "objeto": "Processo",
  "especificacaoObjeto": "Ordem judicial",
  "formato": "DOCUMENTO",
  "eventoId": "a50ea021-43ab-495a-a229-c7a273125c3b",
  "eventoUrl": "https://gateway.stg.cloud.pje.jus.br/notificacao/api/v1/eventos/a50ea021-43ab-495a-a229-c7a273125c3b",
  "notificacaoId": "77b5581e-c96d-4d4f-a0f0-53511d1c4814",
  "modeloEvento": {
    "id": "8bf5b4c6-e80e-4d3d-8807-b96677903493",
    "nome": "OrdemProtocolada",
    "descricao": "Ordem judicial de bloqueio de valores ou requisição de informações",
    "servicoId": "SISBAJUD",
    "grupoServicoId": "SISBAJUD",
    "modelo": "OrdemJudicialVODomainEvent"
  },
  "servico": {
    "id": "SISBAJUD",
    "nome": "SISBAJUD",
    "identificadorGrupo": "SISBAJUD",
    "url": "http://gateway.stg.cloud.pje.jus.br/SISBAJUD/v2/api-docs",
    "versao": "1.16.0"
  },
  "autorAcao": {
    "uuid": "d2bb94a7-a3c5-4a43-a62d-33b98b7db12e",
    "nome": "ADRIANO DA SILVA ARAUJO",
    "documentoIdentificacaoPrincipalValor": "000.000.000-00",
    "documentoIdentificacaoPrincipalTipo": "CPF",
    "justificativaAusenciaDocumentoIdentificacao": null
  },
  "origemAcao": {
    "siglaTribunal": "TJRN",
    "codigoSegmentoJustica": "JCE",
    "identificadorGrauJurisdicao": 0,
    "outrosIdentificadores": null,
    "jtr": "820"
  },
  "numeroUnicoProcesso": "5175220-36.2018.8.13.0024",
  "payload": {
    "formato": "DOCUMENTO",
    "nomeEntidadePayload": "DocumentoDTO",
    "conteudo": {
      "descricao": "Certidão SISBAJUD",
      "tipoCodigoNacional": "10",
      "tipoNome": "Certidão",
      "dataHoraCriacao": 1628090043256,
      "sigiloNivel": 0,
      "sigiloNome": "Públicos",
      "variaveis": {
        "dataProtocolo": "2021-08-03T20:04:49.000+00:00",
        "nomeJuiz": "ADRIANO DA SILVA ARAUJO",
        "codOrdemJudicial": "20201016689259",
        "nomeOperador": "null"
      },
      "documento": {
        "uuid": "87eef984-f0c5-4402-83ba-2a3798d09d56",
        "mimetype": "application/pdf",
        "encoding": "UTF-8",
        "hash": {
          "hash": "08bccc202c7a99cb584e69287cc5caf101e1f34f1a10d05e84b0876f506f1495",
          "algoritmo": "SHA-256"
        },
        "conteudoBase64": "JVBERi0xLjQKJf////8KMSAwIG9iago8PCAvVGl0bGUgKFVudGl0bGVkKQovQ3JlYXRvciAoQXNjaWlkb2N0b3IgUERGIDEuNi4wLCBiYXNlZCBvbiBQcmF3biAyLjQuMCkKL1Byb2R1Y2VyIChBc2NpaWRvY3RvciBQREYgMS42LjAsIGJhc2VkIG9uIFByYXduIDIuNC4wKQovTW9kRGF0ZSAoRDoyMDIxMDgwNDEyMTQwMi0wMycwMCcpCi9DcmVhdGlvbkRhdGUgKEQ6MjAyMTA4MDQxMjE0MDItMDMnM.....",
        "assinaturas": [
          {
            "algoritmo": "sha256WithRSAEncryption",
            "hashAssinaturaBase64": "GZY4S3YRhD05bqiFDOebeo4nL6cFxGHtmuxCI......",
            "dataHoraAssinatura": 1628090043430,
            "codificacaoCadeiaCertificados": "PEM",
            "cadeiaCertificadosBase64": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUdF......."
          }
        ]
      },
      "links": {
        "detalhe-ordem": "http://sisbajudh.cnj.jus.br/v2/ordem/20201016689259/recibo"
      }
    },
    "algoritmoHash": "SHA-256",
    "hash": "7b974b0cfc0264ced65a83cc69d6714054fe196dae32567b2614f0c458e7436a",
    "algoritmoAssinatura": "DES",
    "hashAssinado": "337a95f88e9899d0f0f87f3a7176d1164c802e3c31a12a90e92e7def56815928de5182a809711f36597e915427e099516bd497d77022dbdf65a8ffeda685c4b8c3fc6f146bc91ca5"
  },
  "versao": null,
  "criadoEm": 1628021095785,
  "links": {
    "detalhe-ordem": "http://sisbajudh.cnj.jus.br/v2/ordem/20201016689259/recibo"
  }
}

Exemplo de objeto JSON entregue no formato ALERTA

{
  "objeto": "Processo",
  "especificacaoObjeto": "Audiência digital",
  "formato": "ALERTA",
  "eventoId": "3026edd9-73ef-4f8c-b8fd-9262dd874cbb",
  "eventoUrl": "http://gateway.stg.cloud.pje.jus.br:8880/api/v1/eventos/3026edd9-73ef-4f8c-b8fd-9262dd874cbb",
  "notificacaoId": "23ef99d8-96f5-402b-bb51-ad2670208648",
  "modeloEvento": {
    "id": "dfe2203c-a318-4f1a-88de-eadae4f242cb",
    "nome": "AudienciaSincronizada",
    "descricao": "Audiência sincronizada com o portal por meio do software audiência digital",
    "servicoId": "PJEMIDIAS",
    "grupoServicoId": "PJEMIDIAS",
    "modelo": "AudienciaDomainEvent"
  },
  "servico": {
    "id": "PJEMIDIAS",
    "nome": "PJEMIDIAS",
    "identificadorGrupo": "PJEMIDIAS",
    "url": "https://wwwh.cnj.jus.br/midias/web/site",
    "versao": "1.0.0"
  },
  "autorAcao": {
    "uuid": "a2777d94-8acc-45fa-8f36-08cfbb7b7135",
    "nome": "LEONARDO LEMES ROSA",
    "documentoIdentificacaoPrincipalValor": "980.661.101-20",
    "documentoIdentificacaoPrincipalTipo": "CPF",
    "justificativaAusenciaDocumentoIdentificacao": null
  },
  "origemAcao": {
    "siglaTribunal": "CNJ",
    "codigoSegmentoJustica": "CNJ",
    "identificadorGrauJurisdicao": 1,
    "outrosIdentificadores": null,
    "jtr": "200"
  },
  "numeroUnicoProcesso": "0001234-95.2010.2.00.0000",
  "payload": {
    "formato": "ALERTA",
    "nomeEntidadePayload": "TextoProcessadoDTO",
    "conteudo": {
      "textoParametrizado": {
        "textoParametrizado": "Atenção!!! No dia: ${dtJuntada}, foi sincronizado o vídeo do tipo ${dsTipoVideo} no processo ${nrProcesso} da vara: ${dsVara}, que pode ser acessado aqui: ${link}",
        "variaveis": [
          "dtJuntada",
          "dsTipoVideo",
          "nrProcesso",
          "dsVara",
          "link"
        ]
      },
      "textoFinal": "Atenção!!! No dia: 01/01/2020, foi sincronizado o vídeo do tipo Inicial no processo 00012318023123123123 da vara: VARA ESPECIALIZADA EM DIREITO BANCÁRIO, que pode ser acessado aqui: http://wwwh.cnj.jus.br/midias/web/audiencia/visualizar?id=8ZDdmMDIxMTBiZTBmMDJjMzdhYzkwZTRlMzhiZGUzOWFOelE0TWc9PQ%2C%2C",
      "variaveisUtilizadas": [
        {
          "nome": "dtJuntada",
          "valor": "01/01/2020"
        },
        {
          "nome": "dsVara",
          "valor": "VARA ESPECIALIZADA EM DIREITO BANCÁRIO"
        },
        {
          "nome": "link",
          "valor": "http://wwwh.cnj.jus.br/midias/web/audiencia/visualizar?id=8ZDdmMDIxMTBiZTBmMDJjMzdhYzkwZTRlMzhiZGUzOWFOelE0TWc9PQ%2C%2C"
        },
        {
          "nome": "dsTipoVideo",
          "valor": "Inicial"
        },
        {
          "nome": "nrProcesso",
          "valor": "00012318023123123123"
        }
      ]
    },
    "algoritmoHash": "SHA-256",
    "hash": "6421228b6d5aa8d226d4efc555f0ab1c2d0eb58f556733944cafc4dab5125cc4",
    "algoritmoAssinatura": "DES",
    "hashAssinado": "9b829f8ce3b2dfcc656e325b82896780edee1eab1fb5be417624a5b81d9f9227df43ee052dcedddc469d446cd7547bae3ea3d70bfc9b5c8becb03279002cf511009e065dd4dcbc23"
  },
  "versao": null,
  "criadoEm": 1628277471774,
  "links": {
    "url": "http://wwwh.cnj.jus.br/midias/web/audiencia/visualizar?id=8ZDdmMDIxMTBiZTBmMDJjMzdhYzkwZTRlMzhiZGUzOWFOelE0TWc9PQ%2C%2C"
  }
}

Informações técnicas sobre o funcionamento do serviço

O serviço (notificações) monitora todos os eventos lançados pelos serviços que compõem a PDPJ, diretamente no broker de mensageria RabbitMQ. Ele faz isso monitorando todas as mensagens lançadas com o routing key padrão da PDPJ.

Para cada evento recebido é verificado se há alguma pessoa inscrita nele, caso haja, são criadas tantas notificações quantas forem as inscrições identificadas e inica-se um processo de esteira de produção com as seguintes etapas:

Filtro das notificações - nesta etapa são executados filtros na mensagem original de acordo com os parãmetros de filtro configurados para cada inscrição no evento, ao final desse processo, muitas notificações serão excluídas e algumas continuarão para a próxima etapa;
Validação de permissões - nessa etapa o serviço verifica o nível de sigilo da informação contida na notificação e se o usuário destinatário tem permissão suficiente para recebê-la, da mesma forma, algumas notificações serão eliminadas nesta etapa e algumas continuarão para o próximo passo;
Identificação do protocolo de envio - nessa etapa, o serviço de notificação separará as notificações de acordo com o protocolo indicado na inscrição do usuário e as notificações serão distribuídas de acordo com o protocolo entre os possíveis: webhooks / emails / mensagem instantânea;
Envio - na etapa de envio da notificação, primeiramente as mensagens serão formatadas de acordo com o template relacionado ao protocolo. Posteriormente acontecerão as tentativas de envio:
Em caso de sucesso no envio, o processo é finalizado e aquele envio computado;
Já no caso de falha de envio, verifica-se se o erro encontrado é um erro recuperável (por exemplo tentativas de envio via webhook que retornem erros de código 5xx são recuperáveis e representam instabilidade na rede, outros erros são considerados não recuperáveis). Então, se for recuperável, haverá outras tentativas de envio até que haja sucesso na entrega ou que se atinja um limite de tentativas.

Tecnologias empregadas

O serviço foi construído com SpringBoot 2.

Este serviço fornece API para manipulação e recuperação de seus recursos utilizando REST, banco de dados relacional e banco não relacional.

Envia mensagens aos endoints externos dos clientes subscritos, bem como aos emails e aos usuários do Telegram.

Linguagem de programação: Java 11. Framework(s): SpringBoot 2.

Configuração do armazenamento de dados

Este serviço utiliza banco de dados PostgreSQL versão 9.6 ou superior. A base de dados deve ter encoding UTF-8. Para a execução do serviço é necessário apenas que já haja o banco criado e que o usuário de banco da aplicação tenha permissão de DDL e DMLs, o próprio serviço criará o banco automaticamente.

Dependências

Menssageria/RabbitMQ - serviço responsável por fazer com que os eventos publicados pelos serviços da PDPJ cheguem ao serviço de notificação;
Postgresql - banco de dados relacional que armazena os dados de consultas do serviço de notificações;
Corporativo Proxy - serviço de integração com o sistema corporativo para recuperar informações do usuario logado.
Serviço de cabeçalho processual da PDPJ - necessário para a validaçao de permissões e a busca de outros dados para o filtro de mensagens.

Papéis e/ou recursos

Role: administrador - responsável pelos endpoints de configuração do registro de serviços monitorados, eventos monitorados e templates de mensagens disponibilizadas;
Role: usuário - responsável por sua inscrição nos serviços disponibilizados, bem como a indicação do protocolo do meio de envio das mensagens.

Filas que escuta

A principal fila que escuta é a: notificacao.step000.yammer.queue que faz um binding com a exchange principal da PDPJ: pdpj.exchange para escutar todos os routingKeys padrões da PDPJ: "*.*.*.*" e também faz binding com a exchange principal da PJeCloud: pje.exchange, para escutar os routingKeys padrões dessa nuvem: "*.*.*.*.*".

Interações com outros serviços

As interações com outros serviços acontecem em dois momentos:

A principal interação é o envio de mensagens:

Ao endpoint de webhook do usuário inscrito no evento;
Ao serviço de email do usuário inscrito nesse protocolo;
Ao serviço de mensagens instantâneas do usuário inscrito.

Outra interação muito importante é a que acontece com o serviço de cabeçalho processual, na qual o serviço de notificações busca dados do processo para permitir um filtro mais adequado do evento gerado, e na interação com a validação de permissões relacionadas ao sigilo da informação contida no evento.

Referências

Apresentações

Release notes

Notas da versão

Contextualização​

Webhooks​

O que são?​

Por que utilizar webhook em vez de uma API?​

O webhook é a única opção?​

Características do serviço de notificações​

Quem pode utilizar?​

Quais os meios de encaminhamento de mensagens?​

Webhook​

E-mail​

Mensagens instantâneas​

Como utilizar o serviço?​

Interface web (front-end)​

API do serviço​

Exemplo de objeto JSON entregue no formato DOCUMENTO​

Exemplo de objeto JSON entregue no formato ALERTA​

Informações técnicas sobre o funcionamento do serviço​

Tecnologias empregadas​

Configuração do armazenamento de dados​

Dependências​

Papéis e/ou recursos​

Filas que escuta​

Interações com outros serviços​

Referências​

Apresentações​

Release notes​