Ir para o conteúdo

Webhooks no Jitterbit App Builder

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, uma aplicação 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 uma 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 na aplicação principal.

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

Esta página também contém uma seção de Solução de problemas abordando 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 de seu próprio servidor de dados, do tipo Webhook API, para receber chamadas HTTP recebidas. Siga estas etapas para criar um:

  1. Navegue até o IDE.

  2. Selecione IDE > Servidores de dados.

  3. Clique em + Servidor. A caixa de diálogo Servidor é aberta:

    caixa de diálogo servidor

    1. Defina valores para o seguinte:

      • Nome do servidor: Digite um nome.

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

      • Tipo de conteúdo da solicitação: Selecione JSON.

      • Tipo de conteúdo da resposta: Selecione JSON.

    2. Clique em Salvar.

    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, encontre o servidor que você acabou de criar e selecione-o. Isso lista o novo servidor no outro painel da tela.

  2. Clique no ícone Abrir registro:

    abrir registro

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

    caixa de diálogo webhook API

  4. A página Serviço Web é aberta. No painel Endpoints, clique em + Endpoint:

    página serviço web

    Defina valores para os seguintes parâmetros:

    • Nome: Escolha um nome para seu endpoint.

    • Endpoint: Você pode deixar este campo vazio.

    • Método: 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 Descobrir. A caixa de diálogo Endpoint é aberta:

    caixa de diálogo endpoint

    1. Defina valores para o seguinte:

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

      • Endpoint: Você pode deixar este campo vazio.

      • Método: Selecione POST.

      • Corpo da solicitação: Se o webhook aceita 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 Descobrir. O App Builder adiciona automaticamente os parâmetros do endpoint.

Etapa 2: Adicionar o webhook à sua aplicação

Com o servidor webhook e endpoint definidos, vincule esse servidor à sua aplicação como uma fonte de dados:

  1. Acesse App Workbench > Fontes de Dados.

  2. Clique em + Fonte. Uma caixa de diálogo é aberta.

  3. Selecione Vincular a uma fonte existente.

  4. Clique em Próximo.

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

  6. Clique no botão Vincular.

  7. Clique em Concluído.

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

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

  1. Acesse App Workbench > Fontes de Dados.

  2. No painel Fontes de Dados do App, selecione a fonte de dados de webhook que você acabou de criar:

    criar uma regra

  3. No painel Regras, clique em + Regra. O Construtor de Regras é aberto.

  4. Configure sua nova regra da seguinte forma:

    • Nome: Digite um nome descritivo para a regra, por exemplo, WebhookCreation.

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

    • Fonte de Dados de Origem: Selecione a fonte de dados de webhook da Etapa 1.

    • Destino: Selecione o endpoint de webhook da Etapa 1.

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

  6. No painel Tabelas, clique em + Tabelas. Uma caixa de diálogo é aberta.

  7. Selecione o endpoint de webhook clicando em seu botão Adicionar. Ele aparece no painel Tabelas.

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

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

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

  1. Na tela de edição da regra de negócio que você criou na Etapa 3, clique em Eventos no painel Regra. A caixa de diálogo Todos os Eventos é aberta.

  2. Clique duas vezes na linha com o evento Insert. A janela Insert é aberta:

    janela insert

  3. No painel Informações do Evento, selecione Atualização de Linha no menu Escopo de Atualização.

  4. No painel Ações, clique em + Regra e Registrar. Uma nova instância do Construtor de Regras é aberta. Configure-a da seguinte forma:

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

    • Finalidade: Selecione XP CRUD.

    • Ação: Selecione Insert.

    • Camada de Destino: Selecione Camada de Lógica.

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

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

  6. No painel Tabelas, clique em + Tabelas.

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

  8. Selecione todas as suas colunas.

  9. Clique em Validar.

Etapa 5: Expor o webhook

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

  1. Selecione IDE > APIs REST.

  2. Acesse a guia Webhooks.

  3. No painel Serviços, clique no botão Gerenciar Endpoints para abrir a caixa de diálogo Aplicativos:

    Caixa de diálogo Aplicativos

  4. Localize seu aplicativo e clique em seu ícone de lápis.

  5. Digite um nome para seu endpoint e clique em Prosseguir.

  6. (A partir do App Builder 4.67.) Clique no ícone Autenticação do aplicativo. A caixa de diálogo Provedores de Autenticação é aberta. Adicione os provedores de chave de API, HTTP ou Servidor de Autorização que você deseja permitir para autenticar as solicitações de Webhook deste aplicativo. Consulte Configurar um endpoint para as etapas exatas.

  7. Saia da caixa de diálogo. No painel Serviços, clique no ícone de divisa no bloco do seu aplicativo. A página Webhook API é aberta, exibindo os painéis Serviço e Webhooks.

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

    More menu, Configure Authentication button

    A mesma caixa de diálogo Authentication Providers da etapa 6 é aberta. Adicione e salve provedores da mesma forma descrita lá.

  9. No painel Webhooks, clique em + Webhook. A caixa de diálogo Webhook é aberta:

    Webhook dialog

    Configure-a da seguinte forma:

    • Webhook: Selecione a regra de webhook que você criou. Após salvar a caixa de diálogo, 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 a caixa de diálogo Webhook, onde você pode configurar plugins de solicitaçã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 em sua linha. A caixa de diálogo User é aberta:

    user dialog

  3. Clique em More > Keys. A caixa de diálogo Keys é aberta.

  4. Clique em Create. A caixa de diálogo Generate Key é aberta.

  5. Configure a nova chave da seguinte forma:

    • Provider: Selecione seu provedor de segurança de Chave de API (consulte Set up a security provider API key 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.

Importante

Anote as informações, pois não podem ser exibidas novamente.

user dialog

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 exemplo de corpo 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 de Chave de API.

  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 de autenticação de webhook, consulte Webhook: HTTP Basic Auth requires the Authorization header in the payload no Guia de solução de problemas do App Builder.