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 chamada de API para um endpoint do App Builder 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 App Builder é quando um aplicativo do App Builder envia um email a um usuário solicitando a aprovação ou rejeição de uma transferência. O usuário responderia ao email digitando "aprovar" ou "reprovar" no corpo da mensagem. Se o usuário responder com "aprovar", o App Builder invoca um evento; "reprovar", 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 App Builder usado 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 de pedidos tem um OrderID (PK), nome da empresa, nome do produto e OrderNumber:

Etapa 1: adicionar webhook em servidores de dados

1. 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 pop-up:

     

2. Criar Endpoint:

   • Clique no botão Detalhes do Servidor de Dados
   • Clique no botão Endpoints
   • Clique em + Endpoint no painel Endpoints

   • Nomeie seu endpoint. Por exemplo: PostOrder

     Nota

     Este nome não aparecerá no URL do Webhook.

   • Selecione o Método HTTP que seu Webhook usa. Normalmente, será um POST para atualizar informações em uma tabela.

   • Clique no ícone marca de seleção para salvar

3. Criar parâmetros de Endpoint:

   • Clique em Descobrir no painel Endpoints

   • Se o Webhook aceitar um corpo (por exemplo, um POST usando JSON ou tipo de conteúdo de solicitação XML), forneça um exemplo de Corpo de Solicitação. Para o 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.

4. Se desejar, adicione o parâmetro de endpoint de resposta. No nosso exemplo, seria do tipo String, comprimento -1 caracteres, sem valor de teste, sem tipo selecionado para Cookie/Cabeçalho/Consulta e Direção como Saída.

Etapa 2: adicione webhook ao seu aplicativo

1. Navegue até App Workbench > Fontes de dados
2. Clique em + Fonte
3. Selecione Link para fonte existente
4. Clique em Avançar
5. Selecione a REST Webhook API configurada na Etapa 1
6. Clique no botão Link
7. Revise o resumo do que o App Builder executará e clique em Concluído

Etapa 3: criar uma regra de negócios de webhook

1. Navegue até App Workbench > Regras.
2. Confirme se a Fonte de Dados do Aplicativo selecionada é a sua fonte de dados do Webhook recém-criada e não a fonte de dados do aplicativo.

3. Clique em + Regra

   

4. Atribua um Nome. Por exemplo: Pedido (Webhook)

5. Selecione Webhook como Propósito
6. Selecione a fonte de dados do Webhook como Fonte de dados de origem
7. Defina Destino para o endpoint do Webhook
8. Clique em Salvar
9. Adicione sua tabela Endpoint e selecione todas as colunas. No nosso exemplo, esta é a tabela PostOrder.

Etapa 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 do seu Aplicativo. Crie uma Regra de Negócios XP CRUD que insira o valor recebido do Webhook em uma tabela na Fonte de Dados do seu Aplicativo. Isso deve ser registrado na fonte de dados do Webhook, como o objeto Webhook que acabamos de criar. Algumas observações:

• A tabela de pedidos deve permitir Leitura/Gravação pública, que pode ser configurada nas configurações de Casos Extremos da tabela de pedidos no design da tabela.
• A camada de destino deve ser definida como Camada Lógica.

Adicionaremos uma coluna para gerar uma PK usando o newuuid() função e adicione as colunas Empresa e Produto do nosso objeto webhook com os alvos apropriados:

Etapa 5: Criar 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.

1. Crie uma nova regra XP CRUD registrada na fonte de dados do Webhook. Por exemplo, PostOrder (Atualizar Resposta)
2. Defina a ação como Atualizar
3. Fonte de Dados de Origem para a Fonte de Dados do seu aplicativo
4. Fonte de Dados de Destino para a Fonte de Dados do seu Webhook
5. Defina a Camada de Destino como Camada Lógica
6. Defina o Destino como o seu Objeto Webhook. Por exemplo, Order Webhook
7. Adicione a tabela Order da Fonte de Dados do aplicativo
8. Adicione a Coluna OrderNumber direcionada à coluna Response

9. Adicione a cláusula Where que filtra com base no pedido recém-gerado (utilizamos a função gerada para recuperar o OrderID gerado neste evento)

   

Etapa 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ócios Webhook.

Etapa 7: exponha o webhook ao mundo

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

1. Navegue até App Builder IDE > REST APIs (em Conectar) > Webhooks
2. Clique no botão Gerenciar Endpoints
3. Selecione o aplicativo para o qual deseja inserir o valor do endpoint. Por exemplo: WebhookDocumentation.
4. Clique no ícone de edição de lápis do aplicativo que você está configurando
5. Insira o valor do Endpoint no campo Endpoint. Por exemplo, WebhookDoc
6. Clique em continuar para salvar
7. Para configurar o Objeto Webhook, no Painel Webhooks clique em +Webhook
8. Selecione seu Objeto Webhook. Ele selecionará automaticamente um Nome de Endpoint. Este se tornará a parte do webhook do URL do Webhook.

9. 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.

1. Navegue até o IDE, Provedores de Segurança
2. Em Autenticação de Usuário, crie um registro do tipo Autenticação HTTP Básica caso ainda não exista. Se existir, você pode pular esta etapa.
3. Navegue até IDE, Gerenciamento de Usuários
4. Selecione o usuário que precisa de uma chave
5. Em Autenticação, clique em Chaves
6. Clique em Criar
7. Para Provedor, selecione o provedor de segurança do tipo Autenticação Básica HTTP nas etapas 1 e 2
8. Clique em Salvar
9. 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 o Postman ou o Insomnia. Envie uma chamada de API POST com um Corpo semelhante ao do Exemplo de Corpo 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 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 x-api-key no cabeçalho, você pode ajustar a URL para uma destas opções:

1. https://{{identificador do usuário da Etapa 8.9}}:{{chave do usuário da Etapa 8.9}}@{{url da etapa 9}}(a 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 de autorização seja incluído no payload recebido. Para contornar isso, use o método de chave de API.

2. https://{{url da etapa 9}}?apiKey={{chave do usuário da Etapa 8.9}} (a ser usado se o provedor for a chave de API e as propriedades incluírem HttpHeaderName 'X-API-Key')