Webhooks no App Builder do Jitterbit

Visão geral

Um webhook é uma notificação automatizada enviada entre aplicações quando um evento específico ocorre. O App Builder usa webhooks para disparar ações específicas em resposta a emails, mensagens de texto ou chamadas de API.

Por exemplo, um aplicativo pode enviar um email a um usuário para aprovar ou rejeitar uma transferência. Se o usuário responder "aprovar", um webhook dispara o processo de aprovação; se responder "rejeitar", dispara a rejeição. Isso permite que os usuários concluam tarefas diretamente da sua caixa de entrada ou aplicativo de mensagens sem precisar fazer login novamente no aplicativo principal.

Esta página ensina as etapas para criar e configurar um webhook:

• Etapa 1: adicionar um servidor de dados webhook
• Etapa 2: adicionar o webhook ao seu aplicativo
• Etapa 3: criar uma regra de negócio webhook
• Etapa 4: criar uma regra de negócio CRUD XP
• Etapa 5: expor o webhook
• Etapa 6: criar uma chave de API para um usuário
• Etapa 7: testar o webhook

Esta página também contém uma seção Solução de problemas que aborda um erro comum de webhook e como resolvê-lo.

Criar um webhook

Siga estas etapas para configurar e expor um webhook de ponta a ponta:

Etapa 1: adicionar um servidor de dados webhook

Um webhook precisa do seu próprio servidor de dados, do tipo Webhook API, para receber chamadas HTTP recebidas. Siga estas etapas para criar um:

1. Acesse o IDE.

2. Selecione IDE > Data Servers.

3. Clique em + Server. A caixa de diálogo Server abre:

   

   1. Defina valores para o seguinte:

      • Server Name: insira um nome.

      • Type: selecione Webhook API. Isso faz com que mais opções sejam exibidas.

      • Request Content Type: selecione JSON.

      • Response Content Type: selecione JSON.

   2. Clique em Save.

   3. Saia da caixa de diálogo.

Com o servidor criado, defina o endpoint específico que o webhook chamará:

1. Na lista de servidores, localize o servidor que você acabou de criar e selecione-o. Ao fazer isso, o novo servidor é listado no outro painel na tela.

2. Clique no ícone Open record:

   

3. A caixa de diálogo Webhook API abre. Na seção REST API, clique em Endpoints:

   

4. A página Web Service abre. No painel Endpoints, clique em + Endpoint:

   

   Defina valores para os seguintes parâmetros:

   • Name: escolha um nome para seu endpoint.

   • Endpoint: você pode deixar esse campo em branco.

   • Method: selecione POST.

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

Por fim, descubra os parâmetros que o corpo da solicitação do webhook fornecerá:

1. No painel Endpoints, clique em Discover. A caixa de diálogo Endpoint abre:

   

   1. Defina valores para o seguinte:

      • Name: este campo é preenchido automaticamente com o nome que você escolheu para o endpoint.

      • End Point: você pode deixar este campo em branco.

      • Method: selecione POST.

      • Request Body: se o webhook aceitar um corpo (por exemplo, um POST usando JSON ou tipo de conteúdo de solicitação XML), forneça um corpo de solicitação de exemplo. Por exemplo:

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

   2. Clique em Discover. O App Builder adiciona automaticamente os parâmetros do endpoint.

Etapa 2: adicionar o webhook ao seu aplicativo

Com o servidor webhook e o endpoint definidos, vincule esse servidor ao seu aplicativo como uma fonte de dados:

1. Acesse App Workbench > Data Sources.

2. Clique em + Source. Um diálogo se abre.

3. Selecione Link to existing source.

4. Clique em Next.

5. Localize e selecione a REST Webhook API que você configurou na Etapa 1 na lista.

6. Clique no botão Link.

7. Clique em Done.

Etapa 3: Criar uma regra de negócio de webhook

Em seguida, crie uma regra de negócio que mapeie os dados de entrada do webhook para uma fonte de dados utilizável:

1. Acesse App Workbench > Data Sources.

2. No painel App Data Sources, selecione a fonte de dados webhook que você acabou de criar:

   

3. No painel Rules, clique em + Rule. O Rule Builder se abre.

4. Configure a nova regra da seguinte forma:

   • Name: Insira um nome descritivo para a regra, por exemplo, WebhookCreation.

   • Purpose: Selecione Webhook. Isso faz com que mais opções apareçam.

   • Source Data Source: Selecione a fonte de dados webhook da Etapa 1.

   • Target: Selecione o endpoint webhook da Etapa 1.

5. Clique em Create. O App Builder cria a regra e exibe sua tela de edição.

6. No painel Tables, clique em + Tables. Um diálogo se abre.

7. Selecione o endpoint webhook clicando em seu botão Add. Ele aparece no painel Tables.

8. No painel Tables, selecione todas as colunas do endpoint.

Etapa 4: Criar uma regra de negócio XP CRUD

A regra webhook sozinha apenas define a forma dos dados de entrada. Anexe uma regra XP CRUD ao seu evento Insert para que os dados fiquem disponíveis para outras regras e tabelas em sua aplicação:

1. Na tela de edição da regra de negócio que você criou na Etapa 3, clique em Events no painel Rule. O diálogo All Events se abre.

2. Clique duas vezes na linha com o evento Insert. A janela Insert se abre:

   

3. No painel Event Information, selecione Row Refresh no menu Refresh Scope.

4. No painel Actions, clique em + Rule & Register. Uma nova instância do Rule Builder se abre. Configure-a da seguinte forma:

   • Name: Dê um nome descritivo, por exemplo, WebhookCreation_XP_CRUD.

   • Purpose: Selecione XP CRUD.

   • Action: Selecione Insert.

   • Target Layer: Selecione Logic Layer.

   • Target: Selecione a regra de negócio que você criou na Etapa 3.

5. Clique em Create. A nova regra de negócio é criada e sua tela de edição aparece.

6. No painel Tables, clique em + Tables.

7. Selecione o endpoint que você criou na Etapa 1 clicando em seu botão Add. Ele será exibido no painel Tables.

8. Selecione todas as suas colunas.

9. Clique em Validate.

Etapa 5: Expor o webhook

Por fim, exponha a regra webhook através da REST API do App Builder para que sistemas externos possam chamá-la via HTTP:

1. Selecione IDE > REST APIs.

2. Acesse a aba Webhooks.

3. No painel Services, clique no botão Manage Endpoints para abrir o diálogo Applications:

   

4. Localize sua aplicação e clique em seu ícone lápis.

5. Insira um nome para o seu endpoint e clique em Proceed.

6. (A partir do App Builder 4.67.) Clique no ícone Authentication da aplicação. O diálogo Authentication Providers se abre. Adicione os provedores de chave de API, HTTP ou Authorization Server que você deseja permitir para autenticar as solicitações Webhook dessa aplicação. Consulte Etapa 2: Configurar um endpoint para as etapas exatas.

   Nota

   Esta opção não está disponível em uma aplicação sealed. Para uma aplicação sealed, clique no ícone em sua coluna Web Service em Manage Applications, que abre o mesmo diálogo Authentication Providers de fora da app.

7. Feche o diálogo. No painel Services, clique no ícone chevron no tile da sua aplicação. A página Webhook API abre, mostrando os painéis Service e Webhooks.

8. (Desde o App Builder 4.67.) No painel Service, clique em More > Configure Authentication:

   

   O mesmo diálogo Authentication Providers da etapa 6 abre. Adicione e salve provedores da mesma forma descrita lá.

9. No painel Webhooks, clique em + Webhook. O diálogo Webhook abre:

   

   Configure-o da seguinte forma:

   • Webhook: Selecione a regra de webhook que você criou. Depois que o diálogo é salvo, o ícone ao lado deste campo fica clicável, levando você à página Rule Builder da regra no App Workbench.

   • Endpoint: Digite o segmento de caminho onde o webhook é acessado.

   • Compatibility: Deixe a opção padrão. Consulte Compatibility para as opções disponíveis, que também se aplicam aqui.

10. Clique em Save.

11. (Opcional.) Clique no ícone de detalhes do webhook para ver o diálogo Webhook, onde você pode configurar plugins de requisição/resposta que transformam o payload conforme ele passa pelo webhook.

Etapa 6: Criar uma chave de API para um usuário

Por fim, gere uma chave de API para que um usuário específico possa autenticar chamadas para este webhook:

1. Selecione IDE > User Management.

2. No painel Users, selecione um usuário que tenha privilégios de administrador e clique duas vezes na sua linha. O diálogo User abre:

   

3. Clique em More > Keys. O diálogo Keys abre.

4. Clique em Create. O diálogo Generate Key abre.

5. Configure a nova chave da seguinte forma:

   • Provider: Selecione seu provedor de segurança API Key (consulte Etapa 1: Configurar um provedor de segurança de chave de API se você ainda não configurou um).

   • Description: (Opcional) Forneça uma breve descrição.

   • Expires In: (Opcional) Digite um tempo de expiração personalizado.

6. Clique em Save para criar a chave de API.

Etapa 7: Testar o webhook

Você deve testar seu novo webhook (usando, por exemplo, Postman, Insomnia ou ferramentas similares). Envie uma chamada de API POST com um corpo semelhante ao corpo de exemplo usado para criar os parâmetros na Etapa 1. Você deve usar autenticação básica com o identificador e a chave da Etapa 6 como nome de usuário e senha.

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

Quando nenhuma autenticação é necessária, em vez de configurar uma x-api-key no cabeçalho, você pode ajustar a URL para uma das seguintes opções:

1. https://{{user's identifier from Step 6}}:{{user's key from Step 6}}@{{url from Step 7}} (a ser usado se o provedor for HTTP basic auth sem parâmetros)

   Cuidado

   O método HTTP basic descrito acima requer que o cabeçalho Authorization seja incluído no payload recebido. Para contornar isso, use o método API Key.

2. https://{{url from step7}}?apiKey={{user's key from Step 6}} (a ser usado se o provedor for API Key e as Properties incluírem HttpHeaderName 'X-API-Key')

Solução de problemas

Para uma causa comum de falhas na autenticação do webhook, consulte Webhook: Autenticação HTTP Básica requer o cabeçalho Authorization no payload no Guia de solução de problemas do App Builder.