Webhooks

Visão Geral

App Builder suporta a capacidade de invocar um evento em resposta a um email, mensagem de texto ou uma chamada de API para an App Builder endpoint usando Webhooks. Webhooks são callbacks HTTP definidos pelo usuário e são normalmente 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 em App Builder é se an App Builder o aplicativo envia um email para um usuário pedindo para ele aprovar ou rejeitar uma transferência. O usuário responderia ao email, digitando "approve" ou "disapprove" no corpo da mensagem. Se o usuário responder com "approve" App Builder invoca um evento; "disapprove", 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 an App Builder aplicativo que é usado para gerenciamento de pedidos. O usuário quer ser capaz de 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 do pedido 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 da 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

   • Nome seu endpoint. Por exemplo: PostOrder

     Nota

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

   • Selecione o HTTP Método 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. Crie 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 nosso exemplo, nosso JSON é:

     {
         "Company": "Jitterbit",
         "Product": "App Builder"
     }
     

     (Geraremos o OrderID e o OrderNumber como parte dos eventos disparados pelo Webhook)

     

   • Clique em Salvar

   • Clique em Discover. Isso adicionará automaticamente os Endpoint Parameters de entrada.

4. Se desejar, adicione o parâmetro de endpoint Response. Em nosso exemplo, seria do tipo String, Length -1 caracteres, sem valor de teste, sem tipo selecionado para Cookie/Header/Query, e Direction é Output.

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 App Builder irá executar e clicar em Concluído

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

1. Navegue até App Workbench > Rules.
2. Confirme que a App Data Source selecionada é sua fonte de dados Webhook recém-criada e não sua fonte de dados do aplicativo

3. Clique em + Rule

   

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

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

Etapa 4: Crie 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 notas:

• A tabela Order deve permitir Leitura/Gravação pública, que é configurável nas configurações Edge Case da tabela Order 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() função e adicione as colunas Empresa e Produto do nosso objeto webhook com alvos apropriados:

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

Crie uma Regra de Negócios XP CRUD que Atualiza e grava 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 para seu Objeto Webhook. Por exemplo, Order Webhook
7. Adicione a tabela Order da Fonte de Dados do aplicativo
8. Adicione a Coluna OrderNumber direcionando a 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 seu aplicativo. Isso pode já ter sido feito para seu aplicativo.

1. Navegue até App Builder IDE > APIs REST (em Conectar) > Webhooks
2. Clique no botão Gerenciar Endpoints
3. Selecione o aplicativo para o qual você 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 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 Webhook Object. Ele selecionará automaticamente um Endpoint Name. Isso se tornará a parte do webhook do Webhook URL.

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 atribuí-la-emos a um usuário para acessar este Webhook. Isso pode ser feito uma vez para um Service User, ou várias vezes para usuários individuais.

1. Navegue até o IDE, Provedores de segurança
2. Em User Authentication crie um registro do tipo HTTP Basic Authentication se não existir um. 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 Postman ou Insomnia. Envie uma chamada POST API com o Body similar ao Body Sample usado para criar os parâmetros na Etapa 1. Você usará autenticação básica com o identificador como Username e Key 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 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 do passo 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 no payload recebido. Para ignorar isso, use o método API Key.

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