Eventos

// npm install termo_core --save-exact
import * as webhook from "termo_core/webhook";
// ou: import { webhook } from "termo_core";

receber_evento_eventosCopiar link

Publica um evento no hub

Exige o token de aplicativo do TermoAuth (Authorization: Bearer <token>, tipo: aplicativo): é aqui que cada aplicativo publica os eventos dos dados de que é dono. Token de usuário não publica.

Token. O app troca o segredo dele (SEGREDO_DO_APP_GERADO_NO_TERMO_AUTH) por um JWT de 15 minutos em POST /token_de_app do TermoAuth; o termo_core faz isso sozinho. O hub valida o JWT offline pelo JWKS do TermoAuth. O publicador é o aplicativo cujo identificador_no_termoauth é o sub do token; se ele ainda não existir, é criado na hora com o name do token, ativo e sem tipos de evento.

Corpo. JSON de até 1 MiB com o envelope { id, tipo, versao, entidade_id, ocorrido_em, dados }: id é um UUID (de preferência UUIDv7) gerado pelo publicador e é a chave de idempotência; tipo é o nome do tipo de evento no catálogo; versao é o número da versão do esquema (maior que zero); entidade_id tem de 1 a 200 caracteres; ocorrido_em é RFC 3339; dados é validado contra o JSON Schema da versão.

Ordem das verificações. Token, aplicativo ativo, envelope, tipo cadastrado e ativo, publicador dono do tipo, versão cadastrada e não desligada, e os dados contra o contrato. Toda recusa fica registrada nos eventos recusados do painel com o motivo devolvido: token_invalido, aplicativo_inativo, envelope_invalido, tipo_desconhecido, tipo_inativo, publicador_nao_e_dono, versao_inexistente, versao_desligada ou dados_fora_do_contrato.

Idempotência. Um id já recebido responde 200 com situacao: repetido e não cria entregas de novo, então reenviar depois de uma falha de rede é seguro. Aceito, o evento é entregue a todas as assinaturas ativas da versão publicada, pelo menos uma vez cada. Publicar numa versão descontinuada é aceito, mas volta um aviso pedindo a migração.

function receber_evento_eventos(
  credencial_de_acesso: CredencialDeAcesso,
  corpo_da_requisicao: tipos.EnvelopeDoEvento,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<tipos.PublicacaoRepetida>

import { CredencialDeAcesso } from "termo_core";
import { receber_evento_eventos } from "termo_core/webhook";

const credencial_de_acesso = CredencialDeAcesso.token_do_usuario_logado(token_do_usuario);
const resposta = await receber_evento_eventos(credencial_de_acesso, corpo_da_requisicao);

Argumentos

Retorno: Promise<tipos.PublicacaoRepetida> · Rust: Result<tipos::PublicacaoRepetida, ErroAoChamarServico> · veja PublicacaoRepetida.

webhooks_receber_evento_termo_webhookCopiar link

Recebe as entregas do hub como assinante

Pública, sem token do usuário: é onde o próprio TermoWebhook, como assinante, recebe as entregas do hub. A assinatura é conferida pelo crate termo_core (feature webhook_receber) com a chave pública do hub (endereço do hub pelo AMBIENTE + /.well-known/jwks.json) e o id do aplicativo, que é o mesmo do TermoAuth e vem do token de aplicativo (sem variável de ambiente).

Eventos assinados. colaborador.criado v1 cria o acesso e o colaborador de quem ainda não existe aqui, com o perfil de acesso "Acesso inicial" (só leitura em todas as áreas). colaborador.atualizado v1 grava e-mail e master, o nome só quando nome está em campos_alterados, e a troca de perfil liga ou desliga o acesso (virou cliente desliga, voltou a colaborador religa); quem é colaborador e ainda não existe é criado.

Ordem e repetição. A entrega é pelo menos uma vez e sem ordem garantida: a alteração só é aplicada quando o ocorrido_em é mais novo que o do último evento aplicado àquele acesso; o repetido ou atrasado responde 200 sem mudar nada. Tipo que o app não assina responde 200.

function webhooks_receber_evento_termo_webhook(
  parametros: ParametrosDeWebhooksReceberEventoTermoWebhook,
  corpo_da_requisicao: tipos.EntregaRecebida,
  opcoes_da_chamada?: OpcoesDaChamada,
): Promise<void>

import { webhooks_receber_evento_termo_webhook } from "termo_core/webhook";

await webhooks_receber_evento_termo_webhook({ "X-TermoWebhook-Data": 1, "X-TermoWebhook-Chave": "...", "X-TermoWebhook-Destino": "...", "X-TermoWebhook-Assinatura": "..." }, corpo_da_requisicao);

Argumentos

Retorno: Promise<void> · Rust: Result<(), ErroAoChamarServico> · sem corpo na resposta.

TiposCopiar link

Tipos usados pelas funções desta página. O nome é o mesmo nos dois pacotes.

EntregaRecebidaCopiar link

import type { EntregaRecebida } from "termo_core/webhook";

export interface EntregaRecebida {
  dados: Record<string, unknown>;
  entidade_id: string;
  id: string;
  ocorrido_em: string;
  publicador: string;
  recebido_em: string;
  tipo: string;
  versao: number;
}

EnvelopeDoEventoCopiar link

import type { EnvelopeDoEvento } from "termo_core/webhook";

export interface EnvelopeDoEvento {
  dados: Record<string, unknown>;
  entidade_id: string;
  id: string;
  ocorrido_em: string;
  tipo: string;
  versao: number;
}

PublicacaoRepetidaCopiar link

import type { PublicacaoRepetida } from "termo_core/webhook";

export interface PublicacaoRepetida {
  aviso?: string | null;
  id: string;
  situacao: string;
}