Webhooks¶

Visão Geral¶

O Vinyl suporta a capacidade de invocar um evento em resposta a um email, mensagem de texto ou uma chamada de API para um endpoint do Vinyl usando Webhooks. Webhooks são retornos de chamada HTTP definidos pelo usuário e normalmente são acionados por um evento. Quando o evento especificado ocorre, o site de origem faz uma solicitação HTTP para a URL configurada para o Webhook.

Um exemplo de Webhook no Vinyl é se um aplicativo Vinyl envia um email a um usuário solicitando que ele aprove ou rejeite uma transferência. O usuário responderia ao email digitando "aprovar" ou "desaprovar" no corpo da mensagem. Se o usuário responder com "aprovar", o Vinyl invoca um evento; "desaprovar", outro evento é invocado. Este recurso permite que o usuário responda ao email ou mensagem de texto sem sair do aplicativo.

Como Configurar um Webhook¶

Neste exemplo temos uma aplicação Vinyl que é utilizada para gerenciamento de pedidos. O usuário deseja criar um novo pedido por meio de uma chamada de API e receber o número do pedido na resposta da API. O objetivo do Webhook será gerar um novo registro de pedido, calcular o número do pedido e retornar esse número na resposta.

Nossa tabela Order tem um OrderID (PK), nome da empresa, nome do produto e OrderNumber:

Etapa 1: Adicionar Webhook em Servidores de Dados¶

Criar servidor:
- Navegue até IDE, Data Servers e clique em +Servidor
- Atribua um Nome de servidor. Por exemplo: OrderWebhook
- Selecione Tipo como Webhook API em serviços da web
- Escolha o Conteúdo do tipo de conteúdo de solicitação/resposta apropriado. Em nosso exemplo, ambos são JSON
- Clique em Salvar e feche o pop-up:
Criar Endpoint:
- Clique no botão Servidor de dados Detalhes
- Clique no botão Endpoints
- Clique em + Endpoint no painel Endpoints
- Nome seu endpoint. Por exemplo: Pós-pedido
  
  Nota
  
  Este nome não aparecerá na URL do Webhook.
- Selecione o Método HTTP que seu Webhook usa. Normalmente, este será um POST para atualizar informações em uma tabela.
- Clique no ícone marca de seleção para salvar
Crie parâmetros de Endpoint:
- Clique em Discover no painel Endpoints
- Se o Webhook aceitar um corpo (por exemplo, um POST usando o tipo de conteúdo JSON ou XML Request), forneça uma amostra de Corpo da solicitação. Para nosso exemplo, nosso JSON é:
```
{
    "Company": "Jitterbit",
    "Product": "Vinyl"
}
```
  (Iremos gerar o OrderID e o OrderNumber como parte dos eventos acionados pelo Webhook)
- Clique em Salvar
- Clique em Descobrir. Isso adicionará automaticamente os parâmetros de Endpoint de entrada.
Se desejar, adicione o parâmetro de endpoint de resposta. Em nosso exemplo, seria o tipo String, comprimento -1 caracteres, sem valor de teste, nenhum tipo selecionado para Cookie/Cabeçalho/Consulta e Direção é Saída.

Etapa 2: Adicione Webhook ao Seu Aplicativo¶

Navegue até App Workbench > Fontes de dados
Clique em + Fonte
Selecione Link para fonte existente
Clique em Avançar
Selecione REST Webhook API configurado na Etapa 1
Clique no botão Link
Revise o resumo do desempenho do Vinyl e clique em Concluído

Etapa 3: Crie uma Regra de Negócios de Webhook¶

Navegue até App Workbench > Regras.
Confirme se a Fonte de dados do aplicativo selecionada é a fonte de dados do Webhook recém-criada e não a fonte de dados do aplicativo
Clique em + Regra
Atribua um Nome. Por exemplo: Pedido (Webhook)
Selecione Webhook como finalidade
Selecione a fonte de dados do Webhook como Fonte de dados de origem
Defina Target para o endpoint do Webhook
Clique em Salvar
Adicione sua tabela Endpoint e selecione todas as colunas. Em nosso exemplo, esta é a tabela PostOrder.

Etapa 4: Criar Regras de Negócios XP CRUD¶

Crie uma Regra de Negócio XP CRUD que Insere o valor recebido do Webhook em uma tabela na Fonte de Dados da sua Aplicação. Isso deve ser registrado na fonte de dados do Webhook como o objeto Webhook que acabamos de criar. Algumas notas:

A tabela de pedidos deve permitir leitura/gravação pública, que é configurável nas configurações de caso extremo da tabela de pedidos no design da tabela
A camada de destino deve ser definida como Camada Lógica

Adicionaremos uma coluna para gerar um PK usando o newuuid() funcionar e adicionar as colunas Empresa e Produto do nosso objeto webhook com os alvos apropriados:

Nota

Não precisamos adicionar o OrderNumber porque ele é gerado como parte do evento Insert da tabela Order

Etapa 5: Crie uma Regra de Negócios XP CRUD¶

Crie uma regra de negócios XP CRUD que atualize e grave uma resposta com o OrderNumber do novo pedido.

Crie uma nova regra XP CRUD registrada na fonte de dados Webhook. Por exemplo, PostOrder (resposta de atualização)
Defina a ação como Atualizar
Fonte de dados de origem para a fonte de dados do seu aplicativo
Fonte de dados de destino para a fonte de dados do seu Webhook
Defina a camada de destino como Camada Lógica
Defina o destino para seu objeto Webhook. Por exemplo, Encomendar Webhook
Adicionar tabela de pedidos da fonte de dados do aplicativo
Adicione a coluna OrderNumber visando a coluna Response
Adicione a cláusula Where que filtra com base na ordem recém-gerada (utilizamos a função gerada para recuperar o OrderID gerado neste evento)

Nota

A função gerada retorna uma string, então precisamos converter o OrderID como uma string para que isso funcione

Etapa 6: Adicionar as Regras de Negócios CRUD Como Ações¶

Adicione as duas regras de negócios CRUD criadas ao evento de inserção da camada lógica da regra de negócios do Webhook.

Etapa 7: Expor o Webhook ao Mundo¶

Crie um Endpoint para seu aplicativo. Isso pode já ter sido feito para sua aplicação.

Navegue até Vinyl IDE > APIs REST (em Connect) > Webhooks
Clique no botão Gerenciar Endpoints
Selecione o aplicativo para o qual deseja inserir o valor do endpoint. Por exemplo: WebhookDocumentation.
Clique no ícone de edição de lápis do aplicativo que você está configurando
Insira o valor do Endpoint no campo Endpoint. Por exemplo WebhookDoc
Clique em continuar para salvar
Para configurar o objeto Webhook, no painel Webhooks clique em +Webhook
Selecione seu objeto Webhook. Ele selecionará automaticamente um nome de Endpoint. Esta se tornará a parte do webhook da URL do Webhook.
Clique em Salvar

Etapa 8: Crie uma Chave de API para um Usuário Acessar Este Webhook¶

Criaremos uma chave de API básica e a atribuiremos a um usuário para acessar este Webhook. Isso pode ser feito uma vez para um usuário do serviço ou várias vezes para usuários individuais.

Navegue até IDE, Provedores de segurança
Em Autenticação do usuário, crie um registro do tipo Autenticação básica HTTP se não existir. Se isso acontecer, você pode pular esta etapa
Navegue até IDE, Gerenciamento de usuários
Selecione o usuário que precisa de uma chave
Em Autenticação clique em Chaves
Clique em Criar
Para Provedor, selecione o provedor de segurança do tipo Autenticação básica HTTP nas etapas 1 e 2
Clique em Salvar
Anote o Identificador e a Chave gerados, pois essas informações não estarão disponíveis novamente

Etapa 9: Teste¶

Você pode testar este Webhook usando Postman ou Insomnia. Envie uma chamada POST API com o corpo semelhante ao corpo da amostra usado para criar os parâmetros na etapa 1. Você usará a autenticação básica com o identificador como nome de usuário e a chave como a senha da etapa anterior.

Para testar, use o link: https://<url>/webhook/v1/<application-endpoint>/<endpoint>

No cenário em que nenhuma autenticação é necessária, em vez de configurar uma chave x-api no cabeçalho, você pode ajustar o URL para uma destas opções:

https://{{identificador do usuário da Etapa 8.9}}:{{chave do usuário da Etapa 8.9}}@{{url da etapa 9}} (para ser usado se o provedor for http basic auth sem parâmetros)

Cuidado

O método básico HTTP descrito acima requer que o cabeçalho Authorization seja incluído na payload recebida. Para contornar isso, use o método API Key.
https://{{url da etapa 9}}?apiKey={{chave do usuário da Etapa 8.9}} (a ser usado se o provedor for uma chave de API e as propriedades incluírem HttpHeaderName 'X-API-Key')