Webhooks no Jitterbit App Builder

Visão Geral

O App Builder suporta a capacidade de invocar um evento em resposta a um email, mensagem de texto ou uma chamada de API para um endpoint do App Builder usando Webhooks. Webhooks são callbacks HTTP definidos pelo usuário e geralmente 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 um Webhook no App Builder é se um aplicativo do App Builder enviar um email para um usuário pedindo que ele aprove ou rejeite uma transferência. O usuário responderia ao email, digitando "aprovar" ou "rejeitar" no corpo da mensagem. Se o usuário responder com "aprovar", o App Builder invoca um evento; "rejeitar", outro evento é invocado. Esse recurso permite que o usuário responda ao email ou mensagem de texto sem sair do aplicativo.

Como configurar um webhook

Neste exemplo, temos um aplicativo do App Builder que é usado para gerenciamento de pedidos. O usuário deseja poder criar um novo pedido por meio de uma chamada de API e receber o número do pedido na resposta da API. O propósito do Webhook será gerar um novo registro de Pedido, calcular o número do pedido e retornar esse número na resposta.

Nossa tabela de Pedidos tem um OrderID (PK), Nome da Empresa, Nome do Produto e Número do Pedido:

Passo 1: Adicionar webhook nos servidores de dados

Criar Servidor:
- Navegue até IDE, Servidores de Dados e clique em +Servidor
- Atribua um Nome de Servidor. Por exemplo: OrderWebhook
- Selecione o Tipo como Webhook API em serviços web
- Escolha o tipo de Conteúdo de Solicitação/Resposta apropriado, em nosso exemplo ambos são JSON
- Clique em Salvar e feche o popup:
Criar Endpoint:
- Clique no botão Detalhes do Servidor de Dados
- Clique no botão Endpoints
- Clique em +Endpoint no painel de Endpoints
- Nomeie seu endpoint. Por exemplo: PostOrder
  
  Nota
  
  Este Nome não aparecerá na URL do Webhook.
- Selecione o Método HTTP que seu Webhook utiliza. Normalmente, isso será um POST para atualizar informações em uma tabela.
- Clique no ícone de marca de verificação para salvar
Crie Parâmetros de Endpoint:
- Clique em Descobrir no painel de Endpoints
- Se o Webhook aceitar um corpo (por exemplo, um POST usando o tipo de conteúdo JSON ou XML Request), forneça um Corpo de Solicitação de exemplo. Para nosso exemplo, nosso JSON é:
```
{
    "Company": "Jitterbit",
    "Product": "App Builder"
}
```
  (Geraremos 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 desejado, adicione o parâmetro de endpoint de Resposta. Em nosso exemplo, seria do tipo String, Comprimento -1 caracteres, sem valor de teste, sem tipo selecionado para Cookie/Cabeçalho/Consulta, e a Direção é Saída.

Passo 2: Adicionar webhook ao seu aplicativo

Navegue até App Workbench > Fontes de Dados
Clique em + Fonte
Selecione Vincular a fonte existente
Clique em Próximo
Selecione a API Webhook REST configurada no Passo 1
Clique no botão Vincular
Revise o resumo do que o App Builder realizará e clique em Concluído

Passo 3: Criar uma regra de negócios de webhook

Navegue até App Workbench > Regras.
Confirme que a Fonte de Dados do App selecionada é sua nova fonte de dados Webhook e não sua fonte de dados do aplicativo
Clique em + Regra
Atribua um Nome. Por exemplo: Pedido (Webhook)
Selecione Webhook como Propósito
Selecione a Fonte de Dados Webhook como Fonte de Dados
Defina o Alvo para o endpoint do Webhook
Clique em Salvar
Adicione sua tabela de Endpoint e selecione todas as colunas. Em nosso exemplo, esta é a tabela PostOrder.

Passo 4: Criar regras de negócios XP CRUD

Crie uma Regra de Negócios XP CRUD que insira o valor recebido do Webhook em uma tabela na Fonte de Dados da sua Aplicação. Crie uma Regra de Negócios XP CRUD que insira 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, assim como o objeto Webhook que acabamos de criar. Algumas observações:

A tabela de pedidos deve permitir leitura/escrita pública, o que é configurável nas configurações de Caso de Borda 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 a função newuuid() e adicionaremos as colunas Empresa e Produto do nosso objeto webhook com os alvos apropriados:

Nota

Não precisamos adicionar o OrderNumber porque isso é gerado como parte do Evento de Inserção da tabela de pedidos

Passo 5: Criar uma regra de negócios XP CRUD

Crie uma Regra de Negócios XP CRUD que atualiza e escreve uma resposta com o OrderNumber do novo pedido.

Crie uma nova regra XP CRUD registrada na fonte de dados do Webhook. Por exemplo, PostOrder (Atualizar Resposta)
Defina a ação como Atualizar
Fonte de Dados para a Fonte de Dados da sua aplicação
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 como seu Objeto Webhook. Por exemplo, Webhook de Pedido
Adicione a tabela de pedidos da Fonte de Dados da aplicação
Adicione a coluna OrderNumber direcionando para a coluna de Resposta
Adicione uma cláusula Where que filtre com base no pedido recém-gerado (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 em uma string para que isso funcione.

Step 6: Adicione 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ócio Webhook.

Step 7: Exponha o webhook para o mundo

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

Navegue até o App Builder IDE > REST APIs (Sob Conectar) > Webhooks
Clique no botão Gerenciar Endpoints
Selecione a aplicação para a qual deseja inserir o valor do endpoint. Por exemplo: WebhookDocumentation.
Clique no ícone de lápis de edição para a aplicação que você está configurando
Insira o valor do Endpoint no campo Endpoint. Por exemplo, WebhookDoc
Clique em prosseguir para salvar
Para configurar o Objeto Webhook, no Painel de Webhooks clique em +Webhook
Selecione seu Objeto Webhook. Ele selecionará automaticamente um Nome de Endpoint. Isso se tornará a parte do webhook da URL do Webhook.
Clique em Salvar
(Opcional, desde o App Builder 4.51.) Defina a opção de compatibilidade de recurso:
1. Clique no ícone Abrir ícone de registro. O popup Webhook se abre.
2. Abra o menu Compatibilidade, em seguida, selecione uma das seguintes opções:
3. Versão 1: Use o comportamento REST original—os eventos Inserir não são precedidos por eventos Novo. (Padrão para endpoints criados com o App Builder 4.50 e anteriores.)
4. Versão 2: Use um comportamento REST aprimorado—os eventos Novo e quaisquer regras padrão são invocados antes dos eventos Inserir. (Padrão para endpoints criados com o App Builder 4.51 e posteriores.)

Passo 8: Crie uma chave de API para um usuário acessar este webhook

Vamos criar uma chave de API básica e atribuí-la a um usuário para acessar este Webhook. Isso pode ser feito uma vez para um Usuário de Serviço ou várias vezes para usuários individuais.

Navegue até o IDE, Provedores de Segurança
Sob Autenticação de Usuário, crie um registro do tipo Autenticação Básica HTTP se um não existir. Se um já existir, você pode pular esta etapa
Navegue até IDE, Gerenciamento de Usuários
Selecione o Usuário que precisa de uma Chave
Sob Autenticação, clique em Chaves
Clique em Criar
Para Provedor, selecione o provedor de segurança do tipo Autenticação Básica HTTP das 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

Passo 9: Testar

Você pode testar este Webhook usando Postman ou Insomnia. Envie uma chamada de API POST com o Corpo semelhante ao Exemplo de Corpo usado para criar os parâmetros no Passo 1. Você usará 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 um x-api-key no cabeçalho, você pode potencialmente ajustar a URL para uma dessas opções:

https://{{identificador do usuário do Passo 8.9}}:{{chave do usuário do Passo 8.9}}@{{url do passo 9}} (a ser usado se o provedor for autenticação básica http sem parâmetros)

Cuidado

O método básico HTTP descrito acima requer que o cabeçalho de Autorização seja incluído na carga recebida. Para contornar isso, use o método de Chave de API em vez disso.
https://{{url do passo 9}}?apiKey={{chave do usuário do Passo 8.9}} (a ser usado se o provedor for Chave de API e as Propriedades incluírem HttpHeaderName 'X-API-Key')