Skip To Content

Criar e gerenciar webhooks

Um webhook é um mecanismo que permite que um aplicativo forneça a outros aplicativos informações sobre eventos. Como um administrador de portal do ArcGIS Enterprise , você pode criar, gerenciar e configurar webhooks. Você pode configurar seus webhooks para notificá-lo automaticamente quando ocorrerem eventos associados aos itens, grupos e usuários do portal. Após um webhook ser ativado, uma solicitação de HTTP é realizada para uma URL única, de carga útil definida pelo usuário para fornecer informações sobre o evento.

Principais termos

A seguir estão os principais termos do webhook:

  • Evento do Ativação —A operação que você definiu para ativar seu webhook. Por exemplo, você pode configurar seu webhook para ser ativado quando um grupo específico for atualizado em sua organização ou quando um item for compartilhado. Um webhook pode ter mais de um evento de ativação.
  • Carga Útil—Os dados do evento de ativação entregues pelo seu webhook após o evento especificado ter ocorrido. Estas informações são formatadas no JSON. Consulte a seção Carga Útil abaixo para mais informações.
  • A URL da Carga Útil—O local onde a carga útil será enviada. A URL da carga útil pode ser criada utilizando um serviço como Microsoft Power Automate, Zapier ou IFTTT. Você também pode criar seu próprio parâmetro de serviço da web personalizado utilizando uma plataforma de sua escolha.

Exemplo de caso de uso

Os webhooks permitem a integração de fluxos de trabalho entre sistemas e há muitas maneiras de aproveitar os webhooks em sua organização.

Monitorar atividade no ArcGIS Enterprise

Um webhook pode ser utilizado para monitorar a atividade no ArcGIS Enterprise. Por exemplo, você pode se inscrever em todos os eventos associados a um item específico. O webhook é ativado quando as propriedades do item são atualizadas e uma solicitação de HTTPS entrega uma carga útil que contém dados que descrevem o evento. Você decide onde esta carga útil é entregue e pode agir de acordo com o recebimento das informações.

Eventos de ativação suportados

Ao criar seu webhook, você está se inscrevendo para ativar eventos. Como estes eventos são operações do portal, a URI para a operação deve ser fornecida na configuração do webhook. As subseções abaixo descrevem os eventos de ativação disponíveis e a URI associada.

Itens

As propriedades do item que podem ser atualizadas variam entre tipos de itens e há ações exclusivas que ativam a operação de atualizar. Por exemplo, se o item for um mapa da web, a atualização da tag, a configuração de um pop-up ou a alteração do mapa base serão todos eventos de atualização que ativarão o webhook.

A seguinte tabela lista os eventos de ativação para itens do portal suportados, que incluem mapas da web, aplicativos da web, camadas, pacotes, documentos PDF e assim por diante:

Evento de ativaçãoExemplo de URI

Todos os eventos de ativação para todos os itens

/items

Um item está adicionado ao portal

/items/add

Nenhum item está excluído

/items/delete

Nenhum item está atualizado

/items/update

Nenhum item está movido ou sua propriedade está alterada

/items/move

Nenhum item está publicado

/items/publish

Nenhum item está compartilhado

/items/share

Qualquer item é descompartilhado

/items/unshare

A propriedade de nenhum item foi reatribuída

/items/reassign

Todos os eventos de ativação para um item específico

/items/<itemID>

Um item específico está excluído

/items/<itemID>/delete

As propriedades de um item específico estão atualizadas

/items/<itemID>/update

A propriedade de um item específico está alterada ou o item está movido

/items/<itemID>/move

Um item específico está publicado

/items/<itemID>/publish

Um item específico está compartilhado

/items/<itemID>/share

Um item específico está descompartilhado

/items/<itemID>/unshare

A propriedade de um item específico foi reatribuída

/items/<itemID>/reassign

Grupos

Quaisquer alterações gerais realizadas nas configurações do grupo constituem uma atualização. Por exemplo, alterar o acesso de um grupo ativará um evento de atualização.

A seguinte tabela lista os eventos de ativação associados aos grupos:

Evento de ativaçãoExemplo de URI

Todos os eventos de ativação para todos os grupos

/groups

Um grupo esta adicionado

/groups/add

Nenhum grupo está atualizado

/groups/update

Nenhum grupo está excluído

/groups/delete

Proteção de Exclusão está habilitada para qualquer grupo

/groups/protect

Proteção de Exclusão está desabilitada para qualquer grupo

/groups/unprotect

Um usuário é convidado para qualquer grupo

/groups/invite

Um usuário é adicionado para qualquer grupo

/groups/addUsers

Um usuário é removido de qualquer grupo

/groups/removeUsers

Um papel de usuário é atualizado em qualquer grupo

/groups/updateUsers

A propriedade de nenhum grupo foi reatribuída

/groups/reassign

Todos os eventos de ativação para um grupo específico

/groups/<groupID>

Um grupo específico está atualizado

/groups/<groupID>/update

Um grupo específico está excluído

/groups/<groupID>/delete

Proteção de Exclusão está habilitada para um grupo específico

/groups/<groupID>/protect

Proteção de Exclusão está desabilitada para um grupo específico

/groups/<groupID>/unprotect

Um usuário é convidado para um grupo específico

/groups/<groupID>/invite

Um usuário é adicionado para um grupo específico

/groups/<groupID>/addUsers

Um usuário é removido de um grupo específico

/groups/<groupID>/removeUsers

Um papel de usuário é atualizado em um grupo específico

/groups/<groupID>/updateUsers

A propriedade para um grupo específico foi reatribuída

/groups/<groupID>/reassign

Usuários

Um evento de atualização é ativado sempre que uma alteração é realizada no perfil do usuário. No entanto, as alterações realizadas no papel de um usuário, tipo de usuário ou licença não são consideradas uma atualização para o perfil do usuário.

A seguinte tabela lista os eventos de ativação associados aos usuários:

Evento de ativaçãoExemplo de URI

Todos os eventos de ativação para todos os usuários no portal

/users

Um usuário é adicionado à organização

/users/add

Nenhum usuário entrou no portal

/users/signIn

Nenhum usuário saiu do portal

/users/singOut

Nenhum usuário está excluído

/users/delete

O perfil de nenhum usuário está atualizado

/users/update

A conta de nenhum usuário está desabilitada

/users/disable

A conta de nenhum usuário está habilitada

/users/enable

Nenhum usuário recebeu um novo papel

/users/updateUserRole

Nenhum usuário recebeu um novo tipo de usuário

/users/updateUserLicenseType

Todos os eventos de ativação associados a um usuário específico

/users/<username>

Um usuário especificado entrou no portal

/users/<username>/signIn

Um usuário especificado saiu do portal

/users/<username>/signOut

Um usuário específico está excluído

/users/<username>/delete

Um perfil de usuário específico está atualizado

/users/<username>/update

Uma conta de usuário específico está desabilitada

/users/<username>/disable

Uma conta de usuário específico está habilitada

/users/<username>/enable

Um usuário específico recebeu um novo papel

/users/<username>/updateUserRole

Um usuário específico recebeu um novo tipo de usuário

/users/<username>/updateUserLicenseType

Papéis

Um evento de atualização é ativado sempre que uma alteração é realizada em papéis da organização.

A seguinte tabela lista os eventos de ativação associados aos papéis do usuário:

Evento de ativaçãoExemplo de URI

Todos os eventos de ativação para todos os papéis no portal

/roles

Um novo papel está criado

/roles/add

Um papel existente está atualizado

/roles/updated

Um papel existente está excluído

/roles/delete

Cargar Útil

Quando um webhook é ativado, uma carga útil é entregue à URL de carga útil específica no formato JSON. Cada evento segue um esquema de JSON semelhante com informações relevantes para o evento.

ChaveTipoDescrição
webhookName

texto

O nome do webhook que entregou a carga útil.

webhookId

texto

O ID do webhook que entregou a carga útil.

portalURL

texto

A URL do portal para o qual o webhook está registrado.

when

intervalo de tempo

A hora na qual a carga útil foi entregue.

username

texto

O usuário que ativou o evento.

userId

texto

O ID do usuário que ativou o evento.

when

intervalo de tempo

A hora que ocorreu o evento.

operation

texto

A operação executada pelo usuário. Isto pode ser:

  • add
  • addUsers
  • delete
  • disable
  • enable
  • invite
  • move
  • protect
  • publish
  • removeUsers
  • share
  • unprotect
  • unshare
  • update
  • updateUsers
source

texto

O tipo de item no qual a operação foi executada. Isto pode ser item, group ou user.

id

texto

O ID do item de origem no qual a operação foi executada.

properties

objeto

Propriedades adicionais associadas ao evento. Isto pode ser:

  • sharedToGroups — Como um item é compartilhado (groupID, Organização ou Todos)
  • unsharedFromGroups — Como um item é descompartilhado (groupID, Organização ou Todos)
  • removeUserNames — Os nomes de usuário dos usuários removidos de um grupo
  • updateUserNames — Os nomes de usuário dos usuários cujos papéis do grupo foram atualizados.
  • invitedUserNames — Os nomes de usuário dos usuários convidados para um grupo.
  • addedUserNames — Os nomes de usuário dos usuários que foram adicionados a um grupo
  • userRoleUpdatedTo — Um novo papel ao qual o usuário foi atribuído.
  • reassignedTo —O novo usuário ao qual um item ou grupo foi reatribuído.
  • userLicenseTypeUpdatedTo — O novo tipo de usuário ao qual um usuário foi atribuído.
  • name — O nome do papel que foi criado, atualizado ou excluído.

URL de Carga Útil

Uma URL de carga útil deve ser fornecida pelo usuário ao criar um webhook; isto define onde a carga será entregue. Como a carga útil é entregue por meio de uma solicitação HTTPS POST, o receptor do webhook deve ser configurado para se comunicar por HTTPS e ser acessado pelo portal. Você pode usar múltiplos serviços da web, como Microsoft Power Automate, Zapier e IFFT, para configurar fluxos de trabalho personalizados com sua carga útil. Por exemplo, você pode criar um fluxo de trabalho para Microsoft Power Automate receber uma carga útil, analisar e formatar a carga útil e a enviar para um de e-mail alternativo. Alternativamente, você pode criar e personalizar seu serviço da web para receber cargas úteis. Para organizações que restringem o acesso à Internet, a criação de um serviço da web personalizado para receber cargas úteis é recomendado. Consulte nossas amostras de SDK Enterprise para um servlet Java pronto para uso.

Exemplo de carga útil

O seguinte é uma amostra de carga útil ilustrando que um grupo específico foi atualizado:


{
   "info": {
      "webhookName": "Group monitoring",
      "webhookId": "72fed926aeb74c9ca8a22aacddc6725a",
      "portalURL": "https://machineURL/portal/",
      "when": 1543192196521
   },
   "events": [{
      "username": "administrator",
      "userId": "173dd04b69134bdf99c5000aad0b6298",
      "when": 1543192196521,
      "operation": "update",
      "source": "group",
      "id": "173dd04b69134bdf99c5000aad0b6298",
      "properties": {}
   }]
}

Criar um webhook

Os webhooks podem ser administrados somente através do ArcGIS Portal Directory. Utilize as seguintes etapas para criar um webhook:

  1. Navegue até o ArcGIS Portal Directory.
    https://webadaptorhost.domain.com/webadaptorname/sharing/rest
  2. Entre como um administrador.

    Webhooks podem ser criados e gerenciados somente por um administrador.

    A página do usuário de administração é exibida.

  3. Clique no hiperlink ID da Organização ou faça uma solicitação do formulário abaixo, para ir até a página de recursos do Portal Self.
    https://webadaptorhost.domain.com/webadaptorname/sharing/rest/portals/<org Id>
  4. Role até a parte inferior da página, para Webhooks em Recursos Dependentes.
    https://webadaptorhost.domain/com/webadaptorname/sharing/rest/portals/<org Id>/webhooks
  5. Em Operação Suportada, selecione Create Webhook.
  6. Especifique os parâmetros para o seu webhook.

    Consulte a documentação de REST API do webhook para detalhes sobre estes parâmetros.

    Seu webhook agora está listado em webhooks. https://webadaptorhost.domain.com/webadaptorname/sharing/rest/portals/<org Id>/webhooks

Gerenciar webhooks

Você pode gerenciar seus webhooks através do ArcGIS Portal Directory, fazendo uma solicitação do seguinte formulário:

https://webadaptorhost.domain.com/webadaptorname/sharing/rest/<org Id>/webhoooks/<webhookID>.

As operações suportadas para gerenciar seus webhooks são as seguintes:

  • Update Webhook — Atualiza os parâmetros do seu webhook. Você pode atualizar o nome, URL de carga útil, configuração ou eventos de ativação para o webhook especificado.
  • Delete Webhook — Remove o webhook do seu portal.
  • Deactivate Webhook e Activate Webhook — Desativa seu webhook, que impede que as cargas sejam entregues quando o webhook é ativado. Quando o webhook é desativado, a operação Ativar Webhook fica disponível para retomar a entrega de cargas úteis.

A página Notification Status exibe informações relacionadas aos eventos de ativação associados ao webhook específico. Você pode utilizar esta tabela para monitorar seu webhook, como também, detalhes de cargas úteis entregues, como a hora na qual o webhook foi ativado e as respostas recebidas da URL de carga útil e da carga útil entregue. Registros indicando a entrega bem-sucedida de uma carga útil são removidos após um dia. Registros que indicam uma tentativa de entrega com falha são armazenados por sete dias.

Consulte o Webhooks API por exemplos destas operações.

Configurar parâmetros avançados

Há vários parâmetros avançados que podem ser utilizados para personalizar ainda mais seus webhooks. Estes parâmetros serão aplicados a todos os webhooks configurados em seu portal e podem ser acessados de https://webadaptorhost.domain.com/webadaptorname/sharing/rest/portals/<org ID>/webhooks/settings.

A operação Update permite a você atualizar os seguintes parâmetros:

  • Número de tentativas de entrega — Especifica o número de tentativas que serão realizadas para entregar uma carga útil. O padrão são três tentativas e pode ser aumentado até cinco tentativas.
  • Tempo limite de notificação — Especifica o período de tempo que uma conexão aguardará para receber uma resposta. Se uma resposta não for recebida dentro deste intervalo, a conexão expirará e será considerada uma tentativa de notificação com falha.
  • Tempo decorrido entre tentativas de entrega — Especifica o tempo entre cada tentativa de entrega de carga útil. O padrão são 30 segundos e pode ser aumentado para um máximo de 100 segundos ou diminuído para um mínimo de 1 segundo.

Consulte a documentação do webhooks API para mais informações sobre como configurar parâmetros avançados.

Perguntas mais frequentes de Webhooks

Meu ArcGIS Enterprise é desenvolvido em um ambiente desconectado atrás do Firewall da minha organização. Posso ainda configurar webhooks?

Sim. Para configurar webhooks, você precisará utilizar uma URL de carga útil que pode ser acessada pelo seu portal do ArcGIS Enterprise. Para fazer isso, você pode construir um aplicativo personalizado e desenvolvê-lo em seu servidor interno.

O que constitui uma atualização de um item, usuário ou grupo?

Se você subscreveu nas atualizações para seus itens do portal, usuários e grupos, seu webhook ativará sempre que suas propriedades forem atualizadas. Por exemplo, se você subscreveu pelas atualizações de um item específico em seu portal, seu webhook ativaria se uma atualização fosse feita para o título do item, tags ou miniatura. Uma forma fácil para determinar se uma ação constitui uma atualização em seu portal é exemplificar seu tráfego de rede. Qualquer momento que uma ação resulta na operação Atualizar sendo chamada, esta mesma ação também poderá ativar um webhook que está escutando as atualizações.

Eu estou utilizando Integrated Windows Authentication em meu portal do ArcGIS Enterprise. Posso ainda inscrever no usuário que está entrando e saindo do portal (user/<username>/signIn)?

Estes eventos são somente ativados quando um usuário entra e sai via OAuth. Portanto, Integrated Windows Authentication (IWA) e SAML não são suportados. Entretanto, a segurança embutida do portal e PKI suportam os eventos de entrar e sair.

O que acontece se minha URL de carga útil não funcionar ou se estar indisponível? Há uma forma para recuperar uma carga útil que não foi entregue?

Se o portal tentar entregar uma carga útil para uma URL de carga útil não responsiva ou inalcançável, ou receptor de webhook, os parâmetros avançados que você configurou determinará como e quando o portal tenta outra entrega. Se estas tentativas adicionais também falharem na entrega da carga útil, isto contará como uma falha para o deactivationPolicy que você configurar ao criar o webhook. O webhook após esta política ter sido atendida.

Você pode ir para o status de notificação do webhook para visualizar todas as tentativas de entregas de carga útil e determinar se eles foram entregues com sucesso ou não.