Crear webhooks

Como administrador de una organización, puede configurar webhooks para que se notifiquen en su implementación de ArcGIS Enterprise cuando se produzcan eventos específicos. En las siguientes secciones se describe cómo configurar los webhooks de servicios y de organización.

Requisitos previos a crear webhooks

Considere lo siguiente antes de crear webhooks:

• Para utilizar webhooks de organización, su organización debe utilizar ArcGIS Enterprise 10.7 o versiones posteriores. Para utilizar webhooks de servicios, su organización debe utilizar ArcGIS Enterprise 11.0 o versiones posteriores.
• Para crear y administrar webhooks de organización, debe tener asignado el privilegio Webhooks de organización o tener asignado el rol de administrador predeterminado.
• Para crear y administrar webhooks de servicios de geoprocesamiento, debe tener asignado el privilegio Geoprocesamiento o tener asignado el rol de administrador predeterminado.

  Nota:

  Los usuarios que tienen asignado el privilegio Geoprocesamiento también requerirán que el privilegio Publicar capas basadas en servidor se agregue a su rol personalizado.

• Para crear y administrar webhooks de servicios de entidades, debe tener asignado el privilegio Capa de entidades o tener asignado el rol de administrador predeterminado.
• Los receptores de webhook se deben configurar para que se comuniquen a través de HTTPS. Existen algunas opciones que son compatibles con los receptores, como receptores de servicios web de terceros (Microsoft Power Automate, Zapier e IFFT), servicios web personalizados, ArcGIS Notebook Server y ArcGIS Workflow Manager. Para obtener ejemplos de cómo crear servicios web personalizados o empezar a utilizar receptores de terceros, consulte el repositorio de webhooks. Para obtener más información sobre la creación de webhooks de Notebook Server y Workflow Manager, consulte Automatizar flujos de trabajo con ArcGIS Notebooks y Crear trabajos con webhooks, respectivamente.
• Para configurar webhooks para un servicio de entidades, el servicio debe incluir la funcionalidad de edición y tener habilitado el rastreo de cambios sin sincronización.
• Para configurar webhooks para un servicio de geoprocesamiento, el servicio debe ser asíncrono.

Crear un webhook de organización

Los webhooks de organización le permiten suscribirse a desencadenadores de eventos asociados con sus elementos, grupos y usuarios del portal de ArcGIS Enterprise.

Nota:

Los webhooks de la organización se pueden crear a través del sitio web del portal ArcGIS Enterprise o Directorio de Portal for ArcGIS. Para ver una solicitud POST de ejemplo que crea un webhook acerca de eventos relacionados con usuarios, grupos y elementos, consulte la documentación de la API REST Crear webhook.

Crear un webhook de organización en el Directorio de Portal for ArcGIS

Para crear un webhook de organización a través del Directorio de Portal for ArcGIS, siga estos pasos:

1. Vaya al Directorio de Portal for ArcGIS e inicie sesión como miembro con rol de administrador.

   Solo los administradores con el privilegio privilegio Webhooks de organización o miembros a los que se les haya asignado el rol de administrador predeterminado pueden crear y administrar webhooks de organización.

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

   Una vez que haya iniciado sesión, aparecerá la página del recurso Usuario de su cuenta.

2. Haga clic en el hipervínculo Id. de organización o realice una solicitud del siguiente formulario para acceder a la página del recurso Portal Self:
   https://machine.domain.com/webadaptor/sharing/rest/portals/self

3. Desplácese hacia la parte inferior de la página de recursos Self y haga clic en Webhook > Crea webhook para acceder a la operación Crear webhook.
4. Cuando esté en el extremo Crear webhook, proporcione la siguiente información:
   1. Proporcione un nombre único para el webhook en el cuadro de texto Nombre.
   2. Proporcione la URL de carga del receptor webhook en el cuadro de texto URL de carga, que se consultará mientras se crea el webhook para garantizar que se pueda llevar a cabo una conexión correcta entre su receptor y el portal de ArcGIS Enterprise.

      A continuación, se muestra un ejemplo de URL de carga:

      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. Si lo desea, defina un secreto para el webhook que se pueda usar para autenticar mensajes de webhook con el receptor. Introduzca la cadena alfanumérica definida por el usuario en el cuadro de texto Secreto (opcional).
   4. Si lo desea, especifique la información de desactivación del webhook en el cuadro de texto Propiedades de configuración.

      De forma predeterminada, el webhook se desactiva si se han producido cinco fallos en el curso de cinco días.

   5. En Qué eventos querría que desencadenasen este webhook, seleccione Permitirme definir manualmente o Enviarme todo.
      • Si elige Permitirme definir manualmente, enumere los eventos desencadenadores que se usarán para este webhook en el cuadro de texto Enviarme cambios para estos eventos separados por comas. Por ejemplo, si desea suscribirse a todos los eventos pertenecientes a un grupo específico de su organización, introduzca un evento desencadenador similar al que se muestra a continuación, donde [groupID] representa el Id. único asociado a un grupo específico:
        /groups/[groupID]/update

        Para ver una lista de todos los desencadenadores de eventos compatibles con los webhooks de la organización, consulte Desencadenadores de eventos.
      • Si elige Enviarme todo, se le suscribe a todos los eventos desencadenadores compatibles. Recibirá notificaciones de cada evento a medida que ocurran.
5. Una vez configurados los parámetros anteriores, haga clic en Crear webhook para enviar la solicitud.

   Una vez que la operación se complete, se agregará un nuevo webhook a su organización.

Crear un webhook de organización en el sitio web del portal de ArcGIS Enterprise

Para crear un webhook de organización a través del sitio web del portal de ArcGIS Enterprise, siga estos pasos:

1. Compruebe que haya iniciado sesión como administrador predeterminado o como miembro de un rol personalizado con el privilegio Webhooks de organización.
2. Vaya a Organización > Configuración > Webhooks.
3. Haga clic en Crear webhook.
4. En la ventana Crear webhook, haga lo siguiente:
   1. Proporcione un nombre único para el webhook en el cuadro de texto Nombre.
   2. Seleccione un tipo de webhook en el menú desplegable Tipo.
      • Al seleccionar Todo, se le suscribe a todos los desencadenadores de eventos compatibles. Recibirá notificaciones de cada evento a medida que ocurran.
      • Seleccionar Elementos, Usuarios, Grupos o Roles le permite definir manualmente a qué eventos desencadenadores desea suscribirse.
   3. Si selecciona un tipo de webhook distinto de Todo, aparecerá un menú desplegable adicional relativo al tipo de webhook elegido. Por ejemplo, si seleccionó Elementos para el tipo de webhook, aparece el menú desplegable Elementos, que le permite seleccionar un elemento específico que supervisará el webhook.
   4. Seleccione un evento desencadenador en el menú desplegable Eventos. Por ejemplo, si desea que se invoque el webhook al publicar un elemento específico, seleccione /items/<item ID>/publish.
   5. Seleccione un tipo de receptor de webhook.
      • Si selecciona URL de webhook, proporcione la URL de carga del receptor de webhook. A continuación, se muestra un ejemplo de URL de carga:
        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

      • Si selecciona Notebook, elija el notebook que se ejecutará cuando se desencadene el webhook.

        Nota:

        Si la opción Notebook no está disponible, Notebook Server no se ha configurado con su portal. Si la opción está disponible, pero no se puede seleccionar, no posee ningún notebook adecuado para configurar webhooks. Debe ser el propietario del elemento de notebook que se utilizará para el webhook.

   6. Opcionalmente, defina un valor secreto para el webhook en el cuadro de texto Secreto (opcional). El valor secreto se incluirá en la carga del webhook y se utilizará para autenticar mensajes de webhook con el receptor.
5. Haga clic en Crear webhook.

Configurar parámetros avanzados para webhooks de organización

La configuración avanzada aplicada a los webhooks de su organización le permite personalizar aún más el rendimiento de los webhooks, por ejemplo, especificando el número de intentos de entrega, el tiempo de notificación y el tiempo entre intentos de entrega.

Nota:

Es posible modificar las propiedades avanzadas de los webhooks de organización a través del sitio web del portal de ArcGIS Enterprise o Directorio de Portal for ArcGIS. Para ver una solicitud POST de ejemplo que configura estas propiedades avanzadas, consulte la documentación de la API REST Actualizar configuración de webhook.

Configurar parámetros avanzados en el Directorio de Portal for ArcGIS

Para establecer propiedades avanzadas a través del Directorio de Portal for ArcGIS, haga lo siguiente:

1. Vaya al Directorio de Portal for ArcGIS e inicie sesión como miembro con rol de administrador.

   Solo los miembros a los que se les haya asignado el rol de administrador predeterminado o miembros a los que se les haya asignado el privilegio Webhooks de organización pueden crear y administrar webhooks de organización.

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

   Una vez que haya iniciado sesión, aparecerá la página del recurso Usuario de su cuenta.

2. Haga clic en el hipervínculo Id. de organización o realice una solicitud del siguiente formulario para acceder a la página del recurso Portal Self:
   https://machine.domain.com/webadaptor/sharing/rest/portals/self

3. Desplácese hacia la parte inferior de la página de recursos Self y haga clic en Webhook > Configuración > Actualizar para acceder a la operación Actualizar configuración de webhook.
4. Cuando esté en el extremo Actualizar configuración de webhook, proporcione la siguiente información:
   1. Defina un valor para Número de intentos de notificación.

      Este valor especifica el número de intentos que se realizarán para enviar las cargas de webhooks. De forma predeterminada, el portal de ArcGIS Enterprise intentará enviar cargas 3 veces. El valor de intentos debe ser un entero entre 0 y 5.

   2. Defina un valor para Tiempo de espera de notificación en segundos.

      Este valor especifica el periodo de tiempo, en segundos, que esperará el portal de ArcGIS Enterprise para recibir una respuesta de un receptor. De forma predeterminada, el portal de ArcGIS Enterprise esperará 10 segundos. El valor del número de segundos que el portal de ArcGIS Enterprise esperará debe ser un entero entre 0 y 60 segundos.

   3. Establezca un valor para Tiempo de notificación transcurrido en segundos.

      Este valor especifica la cantidad de tiempo, en segundos, entre cada intento de envío de carga. De forma predeterminada, el portal de ArcGIS Enterprise intentará enviar otra carga después de 5 segundos si se produce un error en el intento anterior hasta que se haya alcanzado el número de intentos especificado en Número de intentos de notificación.

5. Una vez configurados los parámetros anteriores, haga clic en Actualizar configuración de webhook para enviar la solicitud.

   Una vez completada la operación, las propiedades actualizadas se aplicarán a todos los webhooks de la organización configurados.

Configurar parámetros avanzados en el sitio web del portal de ArcGIS Enterprise

Para establecer propiedades avanzadas a través del sitio web del portal de ArcGIS Enterprise, haga lo siguiente:

1. Inicie sesión en su organización como administrador predeterminado o como miembro de un rol personalizado con el privilegio Webhooks de organización.
2. En la parte superior del sitio, haga clic en Organización y haga clic en la pestaña Configuración.
3. Haga clic en Webhooks en el lado izquierdo de la página.
4. Haga clic en Configuración de webhooks avanzada.
5. En la ventana Configuración de webhooks avanzada, haga lo siguiente:
   1. Defina un valor para Número de intentos de envío.

      Este valor especifica el número de intentos que se realizarán para enviar las cargas de webhooks. De forma predeterminada, el portal de ArcGIS Enterprise intentará enviar cargas 3 veces. El valor de intentos debe ser un entero entre 0 y 5.

   2. Defina un valor para Tiempo de espera de notificación.

      Este valor especifica el periodo de tiempo, en segundos, que esperará el portal de ArcGIS Enterprise para recibir una respuesta de un receptor. De forma predeterminada, el portal de ArcGIS Enterprise esperará 10 segundos. El valor del número de segundos que el portal de ArcGIS Enterprise esperará debe ser un entero entre 0 y 60 segundos.

   3. Defina un valor para Tiempo de notificación transcurrido.

      Este valor especifica la cantidad de tiempo, en segundos, entre cada intento de envío de carga. De forma predeterminada, el portal de ArcGIS Enterprise intentará enviar otra carga después de 5 segundos si se produce un error en el intento anterior hasta que se haya alcanzado el número de intentos especificado en Número de intentos de envío.

6. Una vez configurados los ajustes anteriores, haga clic en Guardar.

   Las propiedades actualizadas se aplicarán a todos los webhooks de la organización configurados.

Crear un webhook de servicios de geoprocesamiento

Los webhooks de servicios de geoprocesamiento le permiten suscribirse a desencadenantes de eventos específicos asociados con los servicios de geoprocesamiento.

Nota:

Los webhooks de servicios de geoprocesamiento solo se pueden crear a través del Directorio de administrador de ArcGIS Server. Para ver una solicitud POST de ejemplo que crea un webhook de servicios de geoprocesamiento, consulte la documentación de la API REST Crear webhook .

Para crear un webhook para un servicio de geoprocesamiento, siga estos pasos:

1. Vaya al Directorio de administrador de ArcGIS Server e inicie sesión como miembro con los privilegios apropiados asignados.
   Solo los miembros a los que se les haya asignado el privilegio Geoprocesamiento o el rol de administrador predeterminado pueden crear y administrar webhooks.

   Nota:

   Los usuarios que tienen asignado el privilegio Geoprocesamiento también requerirán que el privilegio Publicar capas basadas en servidor se agregue a su rol personalizado.

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

2. Una vez iniciada la sesión, busque el recurso Webhooks para un servicio de geoprocesamiento haciendo clic en Servicios > [ServiceName] > Webhooks > Crear, donde [ServiceName] representa el servicio para el que se creará el webhook. Para los servicios alojados en carpetas específicas, haga clic en Servicios > [FolderName] > [ServiceName] > Webhooks > Crear, donde [FolderName] representa la carpeta donde se encuentra el servicio.

   Precaución:

   Para configurar webhooks para un servicio de geoprocesamiento, el servicio de geoprocesamiento debe ser asíncrono.

3. Cuando esté en el extremo Crear webhook, proporcione la siguiente información:
   1. Proporcione un nombre único para el webhook en el cuadro de texto Nombre. El nombre proporcionado solo puede incluir valores alfanuméricos, ya que el uso de caracteres especiales dará lugar a un mensaje de error.
   2. Si lo desea, defina un secreto para el webhook que se pueda usar para autenticar mensajes de webhook con el receptor. Introduzca la cadena alfanumérica definida por el usuario en el cuadro de texto Clave de firma.

      Los webhooks de servicio utilizan verificación de firma para garantizar la integridad y seguridad de las cargas de webhook enviadas al receptor de webhook desde ArcGIS Enterprise. La cadena alfanumérica introducida en el cuadro de texto Clave de firma se trata como una clave secreta, que tanto ArcGIS Enterprise como el receptor de webhook conocen y almacenan de forma independiente. Cuando se desencadena un evento de webhook, se pone un hash en la clave secreta y la carga mediante el uso del algoritmo HMAC-SHA256, creando la firma. La firma se pasa a la solicitud de webhook como valor de encabezado de x-esriHook-Signature. Cuando la carga de webhook se suministra al receptor, el receptor utiliza la clave secreta y la carga para crear una firma propia mediante el uso del mismo algoritmo HMAC-SHA256 que ArcGIS Enterprise. Si la firma incluida en el encabezado de solicitud coincide con el valor recalculado por el receptor de webhook, el receptor puede confiar en la carga de webhook. De lo contrario, el receptor puede elegir rechazar la carga de webhook entrante.

   3. Proporcione la URL de carga del receptor webhook en el cuadro de texto URL de hook, que se consultará mientras se crea el webhook para garantizar que se pueda realizar una conexión correcta entre el receptor y ArcGIS Server de la implementación. A continuación, se muestra un ejemplo de carga:
      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. Si lo desea, especifique el tipo de medio. En el menú desplegable Tipo de contenido, elija cualquiera de las siguientes opciones:
      • application/json (predeterminado)
      • application/x-www-form-urlencoded
   5. Si lo desea, defina el formato de las cargas. En el menú desplegable Formato de carga, elija cualquiera de las siguientes opciones:
      • JSON (predeterminado)
      • PJSON
   6. Si lo desea, use el parámetro Activo para deshabilitar o habilitar devoluciones de llamadas cuando se desencadena el webhook. Para habilitarlas, seleccione True. Para deshabilitarlas, seleccione False.

      El valor predeterminado es que las devoluciones de llamadas estén habilitadas.

4. Una vez configurados los parámetros anteriores, haga clic en Crear para enviar la solicitud.

   Una vez completada la operación, se aplica un nuevo webhook al servicio de geoprocesamiento específico.

Nota:

A diferencia de los webhooks de organización y de servicios de entidades, los webhooks de servicios de geoprocesamiento no tienen desencadenadores de eventos definidos por el usuario. Los webhooks de servicios de geoprocesamiento envían cargas una vez que se haya completado un trabajo de geoprocesamiento. Para obtener más información sobre las cargas enviadas para servicios de geoprocesamiento, consulte Cargas.

Crear un webhook de servicios de entidades

Los webhooks de servicios de entidades le permiten suscribirse a desencadenantes de eventos específicos asociados con los servicios de entidades.

Nota:

Los webhooks de servicios de entidades solo se pueden crear a través del Directorio de administrador de ArcGIS Server. Para ver una solicitud POST de ejemplo que crea un webhook de servicios de entidades, consulte la documentación de la API REST Crear webhook .

Para crear un webhook para un servicio de entidades, siga estos pasos:

1. Vaya al Directorio de administrador de ArcGIS Server e inicie sesión como miembro con los privilegios apropiados asignados.
   Solo los miembros a los que se les haya asignado el privilegio Capa de entidades o el rol de administrador predeterminado pueden crear y administrar webhooks.
   https://machine.domain.com/webadaptor/admin

2. Una vez iniciada la sesión, busque el recurso Webhooks para un servicio de entidades haciendo clic en Servicios > [ServiceName] > Webhooks > Crear, donde [ServiceName] representa el servicio para el que se creará el webhook. Para los servicios alojados en carpetas específicas, haga clic en Servicios > [FolderName] > [ServiceName] > Webhooks > Crear, donde [FolderName] representa la carpeta donde se encuentra el servicio.

   Precaución:

   Para configurar webhooks para un servicio de entidades, el servicio de entidades debe incluir la funcionalidad de edición y tener habilitado el rastreo de cambios sin sincronización.

3. Cuando esté en el extremo Crear webhook, proporcione la siguiente información:
   1. Proporcione un nombre único para el webhook en el cuadro de texto Nombre. El nombre proporcionado solo puede incluir valores alfanuméricos, ya que el uso de caracteres especiales dará lugar a un mensaje de error.
   2. Enumere los desencadenadores de eventos que se usarán para este webhook en el cuadro de texto Cambiar tipo. Por ejemplo, para invocar el webhook cada vez que se cree un servicio de entidades, utilice el siguiente desencadenador de evento:

      Ejemplo

      FeaturesCreated

      Para ver una lista de todos los desencadenadores de eventos compatibles con los webhooks de servicios de entidades, consulte Desencadenadores de eventos.
   3. Si lo desea, defina un secreto para el webhook que se pueda usar para autenticar mensajes de webhook con el receptor. Introduzca la cadena alfanumérica definida por el usuario en el cuadro de texto Clave de firma.

      Los webhooks de servicio utilizan verificación de firma para garantizar la integridad y seguridad de las cargas de webhook enviadas al receptor de webhook desde ArcGIS Enterprise. La cadena alfanumérica introducida en el cuadro de texto Clave de firma se trata como una clave secreta, que tanto ArcGIS Enterprise como el receptor de webhook conocen y almacenan de forma independiente. Cuando se desencadena un evento de webhook, se pone un hash en la clave secreta y la carga mediante el uso del algoritmo HMAC-SHA256, creando la firma. La firma se pasa a la solicitud de webhook como valor de encabezado de x-esriHook-Signature. Cuando la carga de webhook se suministra al receptor, el receptor utiliza la clave secreta y la carga para crear una firma propia mediante el uso del mismo algoritmo HMAC-SHA256 que ArcGIS Enterprise. Si la firma incluida en el encabezado de solicitud coincide con el valor recalculado por el receptor de webhook, el receptor puede confiar en la carga de webhook. De lo contrario, el receptor puede elegir rechazar la carga de webhook entrante.

   4. Proporcione la URL de carga del receptor webhook en el cuadro de texto URL de hook, que se consultará mientras se crea el webhook para garantizar que se pueda realizar una conexión correcta entre el receptor y ArcGIS Server de la implementación. A continuación, se muestra un ejemplo de carga:
      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. Si lo desea, especifique el tipo de medio. En el menú desplegable Tipo de contenido, elija cualquiera de las siguientes opciones:
      • application/json (predeterminado)
      • application/x-www-form-urlencoded
   6. Si lo desea, defina el formato de las cargas. En el menú desplegable Formato de carga, elija cualquiera de las siguientes opciones:
      • JSON (predeterminado)
      • PJSON
   7. Si lo desea, use el parámetro Activo para deshabilitar o habilitar devoluciones de llamadas cuando se desencadena el webhook. Para habilitarlas, seleccione True. Para deshabilitarlas, seleccione False.

      El valor predeterminado es que las devoluciones de llamadas estén habilitadas.

   8. Ajuste la programación de webhooks al modificar la información de Segundos en el cuadro de texto Programa. En el caso de servicios de entidades que experimentan muchas ediciones frecuentes, reduzca el valor Segundos para recibir webhooks de forma más frecuente con menos información de eventos en la carga. En el caso de los servicios de entidades que no experimentan cambios frecuentes, aumente el valor de la propiedad Segundos para recibir webhooks con menos frecuencia y que contienen más información de eventos en la carga.

      El valor mínimo y predeterminado para la programación es de 20 segundos.

4. Una vez configurados los parámetros anteriores, haga clic en Crear para enviar la solicitud.

   Una vez completada la operación, se aplica un nuevo webhook al servicio de entidades específico.