Introdução
Webhook’s permitem que você crie ou configure integrações para escutar determinados eventos no UAU e receber atualizações de dados em tempo real. Em vez de exigir que você extraia informações por meio da UAUApi, os webhooks enviarão informações atualizadas para a sua integração conforme elas acontecem.
Eventos
Os eventos são nossa maneira de informar quando algo interessante acontece no UAU. Quando ocorre um evento, o sistema verifica se existe um webhook cadastrado para recebe-lo e na sequência é enviada uma requisição POST para seu endpoint. Cada evento retorna um objeto diferente, veja abaixo a lista de eventos disponíveis bem como o objeto retornado de cada um deles:
- status_venda: Ocorre quando o status de uma venda for alterado. Por exemplo, ao realizar um distrato.
- Empresa: código da empresa vinculada a venda
- Obra: código da obra vinculada a venda
- NumVenda: número da venda
- CodContrato: código do contrato
- CodVendedor: código do vendedor
- CodCliente: código do cliente
- DataVenda: data da venda
- Status: status da venda
- DataCadastro: data de cadastro da venda
- status_unidade: Ocorre quando o status de uma unidade for alterado. Por exemplo, quando uma unidade é vendida.
- NumVenda: número da venda
- Empresa: código da empresa vinculada a unidade
- Obra: código da obra vinculada a unidade
- CodProduto: código do produto geral
- CodPersonalizacao: código da personalização
- CodUnidade código da unidade
- Quantidade: quantidade de unidades
- Status: status da unidade
- Identificador: identificador da unidade
- DataEntregaChaves: data de entrega das chaves
- DataCadastro: data de cadastro
- insert_obra: Ocorre quando uma nova obra for inserida.
- Obra: código da obra
- DescricaoObra: descrição da obra
- Empresa: código da empresa
- ObraFiscal: código da obra fiscal
- TipoObra: tipo da obra
- AtivoInativo: indica se a obra está ativa ou não
- Status: status da obra
- Endereco
- Setor
- Cidade
- UF
- Cep
- Grupo
- CEI
- DataInicio
- DataFim
- DataCadastro
- DataAlteracao
- insert_produto: Ocorre quando um novo produto geral é inserido.
- Empresa: código da empresa
- Obra: código da obra
- CodProduto: código do produto
- CodPersonalizacao: código da personalização
- Cep
- UF
- Cidade
- Bairro
- Logradouro
- Complemento
- Status: status do produto geral
- update_obra: Ocorre quando os dados de uma obra é alterado.
- Obra: código da obra
- DescricaoObra: descrição da obra
- Empresa: código da empresa
- ObraFiscal: código da obra fiscal
- TipoObra: tipo da obra
- AtivoInativo: indica se a obra está ativa ou não
- Status: status da obra
- Endereco
- Setor
- Cidade
- UF
- Cep
- Grupo
- CEI
- DataInicio
- DataFim
- DataCadastro
- DataAlteracao
- update_produto: Ocorre quando os dados de um produto geral é alterado.
- Empresa: código da empresa
- Obra: código da obra
- CodProduto: código do produto
- CodPersonalizacao: código da personalização
- Cep
- UF
- Cidade
- Bairro
- Logradouro
- Complemento
- Status: status do produto geral
- distrato_venda: Ocorre quando é feito o distrato de uma venda.
- Dt. Cancelamento – Data de cancelamento do Distrato;
- Empresa – Código da empresa
- Obra – Código da obra
- NumVend – Número da venda no sistema
- Cliente – Código do cliente
- Nome – Nome do cliente
- ValorVenda – Valor da venda
- ValorRecebido – Valor recebido + pago por clientes anteriores
- Total Distrato – Valor a ser devolvido para o cliente
- Status da Venda – Informação se a venda está normal ou cancelada
- Saldo retido – Soma dos campos (-) Descontos inseridos, (-) Custas a receber e (-) Parcelas de seguro
- Motivo do Distrato – Categoria de distrato selecionada
- cessão_venda: Ocorre quando é feito a cessão de direito de uma venda.
- Data Cessão – Data da cessão de direitos;
- Empresa – Código da empresa;
- Obra – Código da obra;
- NumVend – Número da venda no sistema;
- Cliente – Código do cliente;
- Nome – Nome do cliente;
- ValorVenda – Valor da venda;
- Status da Venda – Informação se a venda está normal ou cancelada;
- Núm venda cessão – Número da nova venda no sistema;
- Cliente – Código do novo cliente no sistema;
- Nome – Nome do novo cliente no sistema.
- insert_venda: Ocorre quando uma nova venda é inserida.
- Data de Venda – Data da venda no sistema;
- Empresa – Código da empresa;
- Obra – Código da obra;
- NumVend – Número da venda no sistema;
- Código cliente principal – Que está na tabela de venda.
- manut_venda: Ocorre quando é feito a manutenção de uma venda.
- Empresa – Código da empresa
- Obra – Código da obra
- NumVend – Número da venda no sistema
- Dt. Manutenção – Data da Manutenção da venda;
- Dt. de Cadastro – Data que foi realizado o registro no sistema.
- receb_venda: Ocorre quando é feito o recebimento de parcelas de uma venda.
- Empresa – Código da empresa;
- Obra – Código da obra;
- NumVend – Número da venda no sistema;
- Identificador – Unidade vendida;
- Data Venda – Data da venda;
- Data Rec. – Data em que foi registrado o recebimento no sistema;
- Banco – Banco que foi depositado o recebimento;
- Conta – Conta que foi depositado o recebimento;
- Cedente – Código do cedente que foi gerada a cobrança referente ao recebimento
- Carteira – Carteira de cobrança utilizada para gerar a cobrança referente ao recebimento;
- Cliente – Código do cliente;
- Nome – Nome do cliente;
- Tipo – Tipo da parcela;
- Parc. – Número da parcela;
- Vencimento – Data de vencimento da parcela;
- Pgto Com – Tipo de recebimento;
- Adquirente – Operadora utilizada no terminal que fez o recebimento;
- Terminais pgto – Terminal que foi utilizado no recebimento;
- Cód. Autorização – Código de autorização do recebimento por cartão;
- Val. Parc. Paga – Valor da parcela recebida;
- Rec. Parcial – Informa se o recebimento da parcela foi integral ou parcial;
- Dt. Receb. – Data de recebimento da parcela;
- Usu. Rec. – Descrição do usuário que fez o recebimento;
- Modalidade – Modalidade de recebimento, crédito ou débito;
- Total de parcelas – Número de parcelas do parcelamento do recebimento feito pelo cartão;
- estornoreceb_venda: Ocorre quando é feito o estorno do recebimento de parcelas de uma venda.
- Empresa – Código da empresa;
- Obra – Código da obra;
- Identificador – Unidade vendida;
- Data Venda – Data da venda;
- NumVend – Número da venda no sistema;
- Data Rec. – Data em que foi registrado o recebimento no sistema;
- Banco – Banco que foi depositado o recebimento;
- Conta – Conta que foi depositado o recebimento;
- Cedente – Código do cedente que foi gerada a cobrança referente ao recebimento;
- Carteira – Carteira de cobrança utilizada para gerar a cobrança referente ao recebimento;
- Cliente – Código do cliente;
- Nome – Nome do cliente;
- Tipo – Tipo da parcela;
- Parc. – Número da parcela;
- Vencimento – Data de vencimento da parcela;
- Pgto Com – Tipo de recebimento;
- Adquirente – Operadora utilizada no terminal que fez o recebimento;
- Terminais pgto – Terminal que foi utilizado no recebimento;
- Cód. Autorização – Código de autorização do recebimento por cartão;
- Val. Parc. Paga – Valor da parcela recebida;
- Rec. Parcial – Informa se o recebimento da parcela foi integral ou parcial;
- Dt. Receb. – Data de recebimento da parcela;
- Usu. Rec. – Descrição do usuário que fez o recebimento;
- Modalidade – Modalidade de recebimento, crédito ou débito;
- Total de parcelas – Número de parcelas do parcelamento do recebimento feito pelo cartão;
- Data da volta da parcela – Data em que o recebimento da parcela foi excluído; (RecebePgto.DataDev_Rpg)
- Usuário que efetuou a volta – Usuário que fez a exclusão do recebimento da parcela. (RecebePgtoDivEstorno.UsrCad_rpde).
Criar webhooks
Criar webhook é um processo simples, primeiro acesse a tela Webhook UAU através do menu Utilitários->Configurações de Integração e em seguida clique na aba Webhook UAU.
As permissões da tela Webhook UAU são controladas pelo programa de permissão GECONFIGWEBHOOK.
Clicando em “Adicionar webhook” será aberta uma nova tela para inserir o seu endpoint, bem como selecionar o evento.
Escolha um “Nome” para seu webhook, a “Url” ou endpoint para onde serão realizadas as requisições e o evento que deseja escutar. O nome e url são de preenchimento obrigatório.
Lembrando que o UAU enviará uma requisição POST para essa url ao acontecer determinado evento.
O campo HMAC secret será gerado pelo sistema automaticamente e consiste em uma chave SHA256. O objetivo dessa chave é permitir que se tenha certeza de que o webhook foi enviado pelo UAU e que os dados não foram comprometidos. Falaremos dele com detalhes mais abaixo.
Por fim, selecione o evento e clique em “Gravar”.
Visão geral de webhooks cadastrados
Após adicionar um novo webhook, será exibido no grid superior da tela principal, a lista de webhooks cadastrados e no grid inferior os logs de todas as requisições enviadas para determinado webhook.
Dando duplo clique em qualquer linha do grid superior, abrirá a tela de manutenção do webhook, permitindo, além de visualizar o HMAC gerado, alterar a url, o nome e o evento do webhook.
No grid inferior é possível acompanhar todo o histórico de requisições de determinado webhook através de logs, sendo possível realizar um filtro por período. Sobre as colunas do grid de log’s:
- Detalhes: exibe o payload enviado para a url do webhook.
- Id: identificador único do log.
- Data: Data e hora do envio da requisição.
- Url: exibe a url para onde foi enviada a requisição.
- Evento: exibe o evento vinculado ao webhook.
- Status: exibe o status http da requisição.
Segurança de Webhooks
Para que o UAU possa se comunicar com outras aplicações através de webhook, sugerimos que a URL seja protegida para que requisições maliciosas não possam manipular seus dados.
Requisições HTTPS
Para garantir que os dados sejam criptografados, é obrigatório a utilização de HTTPS na URL do seu webhook, caso a url não seja HTTPS, o sistema não irá permitir a conclusão do cadastro.
HMAC
HMAC é uma forma de verificar a integridade das informações transmitidas entre sistemas, através de uma chave secreta compartilhada entre as partes afim de validar as informações transmitidas na requisição.
Quando um novo webhook é cadastrado, automaticamente é gerado um código HMAC secret e o objetivo dele é permitir que se tenha certeza de que o webhook, ou a requisição, foi enviada pelo UAU e que os dados não foram alterados.
A cada disparo de webhook, o UAU calcula o hash SHA256 da soma dos itens abaixo com o HMAC secret do webhook e envia esse valor no HEADER da requisição pela chave Content-Hmac:
- Method da requisição: no nosso caso sempre é “POST”.
- Body da requisição: o payload que será recebido na resposta da requisição.
- URL: a mesma url cadastrada no webhook.
O servidor que receber a requisição deverá obter o valor da chave Content-Hmac do HEADER da requisição e realizar o mesmo cálculo de hash para verificar se a requisição de fato veio do UAU, para isso basta calcular o hash SHA256 desses itens acima utilizando a chave HMAC secret disponível no webhook cadastrado.
Exemplos de código e validador on-line