Criar webhooks

Como administrador da organização, você pode configurar webhooks para que sua implantação do ArcGIS Enterprise seja notificada quando ocorrerem eventos específicos. As seções abaixo descrevem como configurar webhooks da organização e de serviço.

Pré-requisitos para criação de webhooks

Considere o seguinte antes de criar webhooks:

• Para usar webhooks da organização, sua organização deve estar usando ArcGIS Enterprise 10.7 ou posterior. Para usar webhooks do serviço, sua organização deve estar usando ArcGIS Enterprise 11.0 ou posterior.
• Para criar e gerenciar webhooks da organização, você deve receber o privilégio de webhooks da organização ou ser atribuído ao papel de administrador padrão.
• Para criar e gerenciar webhooks do serviço de geoprocessamento, você deve receber o privilégio de geoprocessamento ou ser atribuído ao papel de administrador padrão.

  Anotação:

  Os usuários atribuídos ao privilégio Geoprocessamento também exigirão que o privilégio Publicar camadas baseadas no servidor seja adicionado ao seu papel personalizado.

• Para criar e gerenciar webhooks do serviço da feição, você deve receber o privilégio da camada de feição ou ser atribuído ao papel de administrador padrão.
• Os receptores de webhook devem ser configurados para se comunicar por HTTPS. Há algumas opções com suporte para receptores, como receptores de serviços da web de terceiros (Microsoft Power Automate, Zapier, e IFFT), serviços da web personalizados, ArcGIS Notebook Server, e ArcGIS Workflow Manager. Para obter exemplos de como criar serviços da web personalizados ou começar a usar receptores de terceiros, consulte o Repositório de webhook. Para saber mais sobre como criar webhooks doNotebook Server Workflow Manager, consulte Automatizar fluxos de trabalho com ArcGIS Notebooks e Criar trabalhos com webhooks, respectivamente.
• Para configurar webhooks para um serviço da feição, o serviço deve incluir o recurso de Edição e ter o controle de rastreamento ativado sem sincronização.
• Para configurar webhooks para um serviço de geoprocessamento, o serviço deve ser assíncrono.

Criar um webhook da organização

Os webhooks da organização permitem assinar ativadores para eventos associados a seus itens, grupos e usuários do portal ArcGIS Enterprise.

Anotação:

Os webhooks da organização podem ser criados por meio de site do portal ArcGIS Enterprise ouArcGIS Portal Directory. Para visualizar um exemplo de solicitação POST que cria um webhook em torno de eventos relacionados a usuários, grupos e itens, consulte a documentação Criar Webhook de REST API.

Criar um webhook da organização no ArcGIS Portal Directory

Para criar um webhook da organização por meio do ArcGIS Portal Directory, siga estas etapas:

1. Navegue até o ArcGIS Portal Directory e entre como um membro com um papel de administrador.

   Os webhooks da organização podem ser criados e gerenciados apenas por administradores com o privilégio de webhooks da organização ou por membros que receberam o papel de administrador padrão.

   https://machine.domain.com/webadaptor/sharing/rest

   Após registrar, a página de recursos do Usuário para sua conta aparece.

2. Clique no hiperlink ID da Organização ou faça uma solicitação no formulário a seguir para acessar a página de recursos do Portal Self:
   https://machine.domain.com/webadaptor/sharing/rest/portals/self

3. Role até a parte inferior da página de recursos Próprio e clique em Webhook > Criar Webhook para acessar a operação Criar Webhook.
4. Uma vez no parâmetro Criar Webhook, forneça as seguintes informações:
   1. Forneça um nome exclusivo para o webhook na caixa de texto Nome.
   2. Forneça a URL da carga útil para o receptor do webhook na caixa de texto URL da Carga Útil, que será consultada enquanto o webhook estiver sendo criado para garantir que uma conexão bem-sucedida possa ser feita entre o receptor e o portal ArcGIS Enterprise.

      Um exemplo de URL de carga útil é demonstrado abaixo:

      https://app.logic.azure.com:443/workflows/b688528a36e246279dc050f936e5ebd4/triggers/manual/paths/invoke?api-version=2016-06-01&sp=%2Ftriggers%2Fmanual%2Frun&sv=1.0&sig=nHP-LBo9x-nSgMi11DSDuwRIUiJr-8yKGCy7OYaT_ow

   3. Opcionalmente, defina um segredo para o webhook que pode ser usado para autenticar mensagens de webhook com o destinatário. Insira a sequência alfanumérica definida pelo usuário na caixa de texto Segredo (Opcional).
   4. Opcionalmente, especifique as informações de desativação do webhook na caixa de texto Propriedades de Configuração.

      Por padrão, o webhook é desativado se ocorrerem cinco falhas ao longo de cinco dias.

   5. Em Quais eventos você gostaria de ativar este webhook, selecione Deixe-me definir manualmente ou Envie-me tudo.
      • Se você escolher Deixe-me definir manualmente, liste os eventos do ativador que serão usados para este webhook na caixa de texto Envie-me alterações para estes eventos separadas por vírgula. Por exemplo, se você deseja se inscrever em todos os eventos pertencentes a um grupo específico em sua organização, insira um evento do ativador semelhante ao demonstrado abaixo, onde [groupID] representa o ID único associado a um grupo específico:
        /groups/[groupID]/update

        Para visualizar uma lista de todos os ativadores de evento com suporte para webhooks da organização, consulte Ativadores de evento.
      • Se você escolher Envie-me tudo, estará se inscrevendo em todos os eventos do ativador suportados. Você receberá notificações para cada evento conforme eles ocorrem.
5. Após os parâmetros acima serem configurados, clique em Criar Webhook para enviar a solicitação.

   Quando a operação for concluída, um novo webhook será adicionado à sua organização.

Criar um webhook da organização por meio de site do portal ArcGIS Enterprise

Para criar um webhook da organização por meio do site de portal do ArcGIS Enterprise, siga estas etapas:

1. Verifique se você está conectado como administrador padrão ou membro de um papel personalizado com o privilégio de webhooks da organização.
2. Navegue até Organização > Configurações > Webhooks.
3. Clique em Criar webhook.
4. Na janela Criar webhook, faça o seguinte:
   1. Forneça um nome exclusivo para o webhook na caixa de texto Nome.
   2. Selecione um tipo de webhook no menu suspenso Tipo.
      • Selecionar Todos o inscreve em todos os ativadores de eventos suportados. Você receberá notificações para cada evento conforme eles ocorrem.
      • Selecionar Itens, Usuários, Grupos ou Papéis permite definir manualmente em quais eventos do ativador deseja se inscrever.
   3. Se você selecionar um tipo de webhook diferente de Todos, um menu suspenso adicional aparecerá, relativo ao tipo de webhook escolhido. Por exemplo, se você selecionou Itens para o tipo de webhook, o menu suspenso Itens aparecerá, permitindo que você selecione um item específico que o webhook monitorará.
   4. Selecione um evento do ativador no menu suspenso Eventos. Por exemplo, se você deseja que o webhook seja solicitado quando um item específico for publicado, selecione /items/<ID do item>/publish.
   5. Selecione um tipo de receptor de webhook.
      • Se você selecionar URL do Webhook, forneça a URL de carga útil para o receptor de webhook. Um exemplo de URL de carga útil é demonstrado abaixo:
        https://app.logic.azure.com:443/workflows/b688528a36e246279dc050f936e5ebd4/triggers/manual/paths/invoke?api-version=2016-06-01&sp=%2Ftriggers%2Fmanual%2Frun&sv=1.0&sig=nHP-LBo9x-nSgMi11DSDuwRIUiJr-8yKGCy7OYaT_ow

      • Se você selecionar Notebook, escolha o notebook que será executado quando o webhook for ativado.

        Anotação:

        Se a opção Notebook não estiver disponível, um Notebook Server não foi configurado com seu portal. Se a opção estiver disponível, mas não puder ser selecionada, você não é proprietário de nenhum notebook adequado para configurar webhooks. Você deve ser proprietário de item do notebook que será usado para o webhook.

   6. Opcionalmente, defina um valor secreto para o webhook na caixa de texto Segredo (Opcional). O valor secreto será incluído na carga útil do webhook e usado para autenticar as mensagens do webhook com o destinatário.
5. Clique em Criar webhook.

Configurar parâmetros avançados para webhooks da organização

As configurações avançadas aplicadas aos webhooks da sua organização permitem personalizar ainda mais o desempenho dos webhooks, como especificar o número de tentativas de entrega, tempo de notificação e tempo entre tentativas de entrega.

Anotação:

Os webhooks da organização podem ter suas propriedades avançadas modificadas por meio de site do portal ArcGIS Enterprise ouArcGIS Portal Directory. Para visualizar um exemplo de solicitação POST que configura essas propriedades avançadas, consulte a documentação Atualizar Configurações do Webhook de REST API.

Configurar parâmetros avançados no ArcGIS Portal Directory

Para definir propriedades avançadas por meio do ArcGIS Portal Directory, faça o seguinte:

1. Navegue até o ArcGIS Portal Directory e entre como um membro com um papel de administrador.

   Os webhooks da organização podem ser criados e gerenciados apenas por membros que receberam o papel de administrador padrão ou membros que receberam o privilégio de webhooks da organização.

   https://machine.domain.com/webadaptor/sharing/rest

   Após registrar, a página de recursos do Usuário para sua conta aparece.

2. Clique no hiperlink ID da Organização ou faça uma solicitação no formulário a seguir para acessar a página de recursos do Portal Self:
   https://machine.domain.com/webadaptor/sharing/rest/portals/self

3. Role até a parte inferior da página de recursos Próprio e clique em Webhook > Configurações > Atualizar para acessar a operação Atualizar Configurações do Webhook.
4. Uma vez no parâmetro Atualizar Configurações do Webhook forneça as seguintes informações:
   1. Defina um valor para Número de Tentativas de Notificação.

      Esse valor especifica o número de tentativas que serão feitas para entregar as cargas úteis do webhook. Navegue até o ArcGIS Enterprise e entre como um membro com um papel de administrador. O valor das tentativas deve ser um número inteiro entre 0 e 5.

   2. Defina um valor para Tempo Limite de Notificação em Segundos.

      Esse valor especifica o tempo, em segundos, que o portal ArcGIS Enterprise aguardará para receber uma resposta de um receptor. Por padrão, o portal ArcGIS Enterprise aguardará 10 segundos. O valor para o número de segundos que o portal ArcGIS Enterprise aguardará deve ser um número inteiro entre 0 e 60 segundos.

   3. Defina um valor para Tempo Decorrido da Notificação em Segundos.

      Esse valor especifica a quantidade de tempo, em segundos, entre cada tentativa de entrega de carga útil. Por padrão, o portal ArcGIS Enterprise tentará entregar outra carga útil após 5 segundos se a tentativa anterior falhar, até que o número de tentativas especificado em Número de Tentativas de Notificação seja atingido.

5. Após os parâmetros acima forem configurados, clique em Atualizar Configurações do Webhook para enviar a solicitação.

   Após a operação ser concluída, as propriedades atualizadas serão aplicadas a cada webhook da organização configurada.

Configurar parâmetros avançados no site de web do portal ArcGIS Enterprise

Para definir propriedades avançadas por meio do ArcGIS Enterprise, faça o seguinte:

1. Entre na sua organização como administrador padrão ou membro de um papel personalizado com o privilégio de webhooks da organização.
2. No parte superior do site, clique em Organização e clique na guia Configurações.
3. Clique em Webhooks no lado esquerdo da página.
4. Clique em Configurações de webhook avançadas
5. Na janela Configurações de webhook avançadas, faça o seguinte:
   1. Defina um valor para Número de tentativas de entrega.

      Esse valor especifica o número de tentativas que serão feitas para entregar as cargas úteis do webhook. Navegue até o ArcGIS Enterprise e entre como um membro com um papel de administrador. O valor das tentativas deve ser um número inteiro entre 0 e 5.

   2. Defina um valor para Tempo limite da notificação.

      Esse valor especifica o tempo, em segundos, que o portal ArcGIS Enterprise aguardará para receber uma resposta de um receptor. Por padrão, o portal ArcGIS Enterprise aguardará 10 segundos. O valor para o número de segundos que o portal ArcGIS Enterprise aguardará deve ser um número inteiro entre 0 e 60 segundos.

   3. Defina um valor para Tempo decorrido da notificação

      Esse valor especifica a quantidade de tempo, em segundos, entre cada tentativa de entrega de carga útil. Por padrão, o portal ArcGIS Enterprise tentará entregar outra carga útil após 5 segundos se a tentativa anterior falhar, até que o número de tentativas especificado em Número de tentativas de notificação seja atingido.

6. Após as configurações acima serem definidas, clique em Salvar.

   As propriedades atualizadas serão aplicadas a cada webhook da organização configurado.

Criar um webhook do serviço de geoprocessamento

Os webhooks do serviço de geoprocessamento permitem assinar ativadores de eventos específicos associados aos serviços de geoprocessamento.

Anotação:

Os webhooks do serviço de geoprocessamento podem ser criados por meio do ArcGIS Server Administrator Directory. Para visualizar um exemplo de solicitação POST que cria um webhook do serviço de geoprocessamento, consulte a documentação Criar webhook de REST API.

Para criar um webhook para um serviço de geoprocessamento, siga estas etapas:

1. Navegue até o ArcGIS Server Administrator Directory e entre como membro com os privilégios apropriados atribuídos a eles.
   Os webhooks podem ser criados e gerenciados apenas por membros atribuídos ao privilégio de geoprocessamento ou ao papel de administrador padrão.

   Anotação:

   Os usuários atribuídos ao privilégio Geoprocessamento também exigirão que o privilégio Publicar camadas baseadas no servidor seja adicionado ao seu papel personalizado.

   https://machine.domain.com/webadaptor/admin

2. Após conectado, navegue até o recurso Webhooks para um serviço de geoprocessamento clicando em Serviços > [ServiceName] > Webhooks > Criar, onde [ServiceName] representa o serviço para o qual o webhook será criado. Para serviços alojados em pastas específicas, clique em Serviços > [FolderName] > [ServiceName] > Webhooks > Criar, onde [FolderName] representa a pasta onde o serviço está localizado.

   Aviso:

   Para configurar webhooks para um serviço de geoprocessamento, o serviço de geoprocessamento deve ser assíncrono.

3. Uma vez no parâmetro Criar Webhook, forneça as seguintes informações:
   1. Forneça um nome exclusivo para o webhook na caixa de texto Nome. O nome fornecido pode incluir apenas valores alfanuméricos, pois o uso de caracteres especiais resultará em uma mensagem de erro.
   2. Opcionalmente, defina um segredo para o webhook que pode ser usado para autenticar mensagens de webhook com o destinatário. Digite a sequência alfanumérica definida pelo usuário na caixa de texto Chave de Assinatura.

      Os webhooks de serviço usam verificação de assinatura para garantir a integridade e a segurança das cargas úteis do webhook enviadas doArcGIS Enterprise para um receptor de webhook. A string alfanumérica inserida na caixa de texto Chave de Assinatura é tratada como uma chave secreta, que é conhecida e armazenada independentemente por ambos o ArcGIS Enterprise e o receptor de webhook. Quando um evento de webhook é ativado, a chave secreta e a carga útil são criptografadas usando um algoritmo HMAC-SHA256, criando a assinatura. A assinatura é então passada na solicitação de webhook como o valor do cabeçalho x-esriHook-Signature. Quando a carga útil do webhook é entregue ao receptor, o receptor usa a chave secreta e a carga útil para criar sua própria assinatura usando o mesmo algoritmo HMAC-SHA256 usado peloArcGIS Enterprise. Se a assinatura incluída no cabeçalho da solicitação corresponder ao valor recalculado criado pelo receptor de webhook, a carga útil do webhook poderá ser confiável para o receptor. Caso contrário, o receptor pode optar por rejeitar a carga útil do webhook recebida.

   3. Forneça a URL de carga útil para o receptor do webhook na caixa de texto URL do Gancho, que será consultada enquanto o webhook estiver sendo criado para garantir que uma conexão bem-sucedida possa ser feita entre o receptor e o ArcGIS Server. Um exemplo de carga útil é demonstrado abaixo:
      https://app.logic.azure.com:443/workflows/b688528a36e246279dc050f936e5ebd4/triggers/manual/paths/invoke?api-version=2016-06-01&sp=%2Ftriggers%2Fmanual%2Frun&sv=1.0&sig=nHP-LBo9x-nSgMi11DSDuwRIUiJr-8yKGCy7OYaT_ow

   4. Opcionalmente, especifique o tipo de mídia. No menu suspenso Tipo de Conteúdo, escolha um dos seguintes:
      • application/json (padrão)
      • application/x-www-form-urlencoded
   5. Opcionalmente, defina o formato das cargas úteis. No menu suspenso Formato de Carga Útil, escolha um dos seguintes:
      • JSON (padrão)
      • PJSON
   6. Opcionalmente, use o parâmetro Ativar para desabilitar ou habilitar retornos de chamada quando o webhook for ativado. Para habilitar, selecione Verdadeiro. Para desabilitar selecione Falso.

      O padrão é que os retornos de chamada estejam habilitados.

4. Após os parâmetros acima serem configurados, clique em Criar para enviar a solicitação.

   Concluída a operação, um novo webhook é aplicado ao serviço de geoprocessamento específico.

Anotação:

Ao contrário dos webhooks de serviço da feição e da organização, os webhooks do serviço de geoprocessamento não têm ativadores de eventos definidos pelo usuário. Os webhooks do serviço de geoprocessamento entregam cargas úteis assim que um trabalho de geoprocessamento é concluído. Para mais informações sobre as cargas úteis entregues para serviços de geoprocessamento, consulte Cargas úteis.

Criar um webhook de serviço da feição

Os webhooks de serviço da feição permitem assinar ativadores de eventos específicos associados a serviços da feição.

Anotação:

Os webhooks do serviço da feição podem ser criados por meio do ArcGIS Server Administrator Directory. Para visualizar um exemplo de solicitação POST que cria um webhook do serviço da feição, consulte a documentação Criar webhook de REST API.

Para criar um webhook para um serviço da feição, siga estas etapas:

1. Navegue até o ArcGIS Server Administrator Directory e entre como membro com os privilégios apropriados atribuídos a eles.
   Os webhooks podem ser criados e gerenciados apenas por membros atribuídos ao privilégio da camada de feição ou ao papel de administrador padrão.
   https://machine.domain.com/webadaptor/admin

2. Após conectado, navegue até o recurso Webhooks para um serviço da feição clicando em Serviços > [ServiceName] > Webhooks > Criar, onde [ServiceName] representa o serviço para o qual o webhook será criado. Para serviços alojados em pastas específicas, clique em Serviços > [FolderName] > [ServiceName] > Webhooks > Criar, onde [FolderName] representa a pasta onde o serviço está localizado.

   Aviso:

   Para configurar webhooks para um serviço da feição, o serviço da feição deve incluir o recurso de edição e ter o controle de rastreamento ativado sem sincronização.

3. Uma vez no parâmetro Criar Webhook, forneça as seguintes informações:
   1. Forneça um nome exclusivo para o webhook na caixa de texto Nome. O nome fornecido pode incluir apenas valores alfanuméricos, pois o uso de caracteres especiais resultará em uma mensagem de erro.
   2. Liste os ativadores de eventos que serão usados para este webhook na caixa de texto Alterar Tipo. Por exemplo, para solicitar o webhook sempre que um serviço da feição for criado, use o seguinte ativador de evento:

      Exemplo

      FeaturesCreated

      Para visualizar uma lista de todos os ativadores de eventos com suporte para webhooks de serviço da feição, consulte Ativadores de eventos.
   3. Opcionalmente, defina um segredo para o webhook que pode ser usado para autenticar mensagens de webhook com o destinatário. Digite a sequência alfanumérica definida pelo usuário na caixa de texto Chave de Assinatura.

      Os webhooks de serviço usam verificação de assinatura para garantir a integridade e a segurança das cargas úteis do webhook enviadas doArcGIS Enterprise para um receptor de webhook. A string alfanumérica inserida na caixa de texto Chave de Assinatura é tratada como uma chave secreta, que é conhecida e armazenada independentemente por ambos o ArcGIS Enterprise e o receptor de webhook. Quando um evento de webhook é ativado, a chave secreta e a carga útil são criptografadas usando um algoritmo HMAC-SHA256, criando a assinatura. A assinatura é então passada na solicitação de webhook como o valor do cabeçalho x-esriHook-Signature. Quando a carga útil do webhook é entregue ao receptor, o receptor usa a chave secreta e a carga útil para criar sua própria assinatura usando o mesmo algoritmo HMAC-SHA256 usado peloArcGIS Enterprise. Se a assinatura incluída no cabeçalho da solicitação corresponder ao valor recalculado criado pelo receptor de webhook, a carga útil do webhook poderá ser confiável para o receptor. Caso contrário, o receptor pode optar por rejeitar a carga útil do webhook recebida.

   4. Forneça a URL de carga útil para o receptor do webhook na caixa de texto URL do Gancho, que será consultada enquanto o webhook estiver sendo criado para garantir que uma conexão bem-sucedida possa ser feita entre o receptor e o ArcGIS Server. Um exemplo de carga útil é demonstrado abaixo:
      https://app.logic.azure.com:443/workflows/b688528a36e246279dc050f936e5ebd4/triggers/manual/paths/invoke?api-version=2016-06-01&sp=%2Ftriggers%2Fmanual%2Frun&sv=1.0&sig=nHP-LBo9x-nSgMi11DSDuwRIUiJr-8yKGCy7OYaT_ow

   5. Opcionalmente, especifique o tipo de mídia. No menu suspenso Tipo de Conteúdo, escolha um dos seguintes:
      • application/json (padrão)
      • application/x-www-form-urlencoded
   6. Opcionalmente, defina o formato das cargas úteis. No menu suspenso Formato de Carga Útil, escolha um dos seguintes:
      • JSON (padrão)
      • PJSON
   7. Opcionalmente, use o parâmetro Ativar para desabilitar ou habilitar retornos de chamada quando o webhook for ativado. Para habilitar, selecione Verdadeiro. Para desabilitar selecione Falso.

      O padrão é que os retornos de chamada estejam habilitados.

   8. Ajuste o agendamento para webhooks modificando as informações de Segundos na caixa de texto Agendar. Para serviços da feição que passam por muitas edições frequentes, diminua o valor de Segundos para receber webhooks mais frequentes com menos informações de eventos na carga útil. Para serviços da feição que não sofrem alterações frequentes, aumente o valor da propriedade Segundos para receber webhooks menos frequentes com mais informações de eventos contidas na carga útil.

      O valor mínimo e padrão para agendamento é 20 segundos.

4. Após os parâmetros acima serem configurados, clique em Criar para enviar a solicitação.

   Concluída a operação, um novo webhook é aplicado ao serviço da feição específico.