Webhook

Los webhooks permiten que varias aplicaciones interactúen entre sí, a través de solicitudes HTTP POST para pasar devoluciones de llamadas entre ellas. Para obtener más información, consulte la página de Wikipedia sobre los webhooks. Entre los usos habituales de webhooks se encuentran: el envío de notificaciones por correo electrónico o SMS, la publicación de mensajes en redes sociales, la escritura automática de registros en una hoja de cálculo y la actualización de bases de datos corporativas.

En Survey123, se pueden configurar y activar webhooks cuando se crea o se elimina un registro de una capa de entidades, o cuando se envía una respuesta a una encuesta. Si desactiva la advertencia y vuelve a publicarla, la capa de entidades original se elimina y se reemplaza, y se pierden todos los datos asociados.

Precaución:

Al crear o modificar un webhook para una encuesta, la encuesta se debe actualizar en la aplicación de campo Survey123 para que los cambios surtan efecto.

Su lugar de trabajo puede contar con su propio proveedor de webhook, pero también dispone de una variedad de servicios de flujo de trabajo de terceros, tales como Microsoft Power Automate, Make, Zapier y tray.io. Todos ellos se pueden utilizar para incorporar Survey123 como desencadenador de un proceso automático.

Microsoft Power Automate y Make también incluyen componentes de flujo de trabajo que facilitan la creación de webhooks para usar con Survey123.

Tipos de webhooks compatibles con Survey123

Survey123 admite dos tipos de webhooks:

• Webhooks de capas de entidades: se almacenan en la capa de entidades o en la vista de la capa de entidades de la encuesta, y se activan desde ahí.
• Webhooks de Survey123: se almacenan en el elemento del formulario de la encuesta y se activan mediante la aplicación móvil o la aplicación web.

Microsoft Power Automate incluye un conector de ArcGIS que ayuda a configurar webhooks de capas de entidades o los webhooks de Survey123. Para obtener más información, consulte Conectores de ArcGIS. Los siguientes componentes del flujo de trabajo que ayudan a configurar un webhook de Survey123 seguirán estando disponibles, pero ya no se actualizarán:

• Microsoft Power Automate: conector de Survey123
• Make: módulo de Survey123

Ejemplos de cómo configurar un webhook

Existen muchas maneras de utilizar Survey123 como desencadenador de sus flujos de trabajo. Los tres primeros ejemplos de esta sección se basan en el mismo escenario —enviar un correo electrónico de notificación cuando se envía una respuesta que contiene una pregunta respondida con un valor determinado—, pero cada uno utiliza un componente de flujo de trabajo de terceros o un tipo de webhook diferente. El último ejemplo parte de la base de que ha creado un webhook personalizado (sin utilizar un conector de Microsoft Power Automate ni un módulo de Make) y describe cómo agregar el webhook a Survey123.

Vea los siguientes ejemplos:

• Configurar un webhook de capa de entidades en Microsoft Power Automate
• Configurar un webhook de Survey123 en Microsoft Power Automate
• Configurar un webhook de Survey123 en Make
• Agregar un webhook en el sitio web de Survey123

Configurar un webhook de capa de entidades en Microsoft Power Automate

Sigue estos pasos para configurar un webhook de capa de entidades en Microsoft Power Automate:

Nota:

Las credenciales de ArcGIS Online que se utilizan para crear flujos en Power Automate cierran la sesión de forma automática después de dos semanas. Si no puede examinar las encuestas esperadas en Power Automate, confirme que su conexión de datos con Survey123 está activa. Para obtener más información, consulte el artículo del blog Consejo rápido: Cómo mantener válido el token de actualización de ArcGIS Connectors for Power Automate.

Para configurar un flujo en Microsoft Power Automate utilizando los conectores de ArcGIS o ArcGIS Enterprise, siga los pasos que se indican a continuación. Si anteriormente creó flujos con el conector de Survey123, estos seguirán funcionando, pero la nueva funcionalidad solo se agregará a los conectores de ArcGIS y ArcGIS Enterprise. Para obtener más información, consulte el artículo del blog Desencadenadores y acciones de Survey123 en ArcGIS Connectors for Power Automate.

1. Abra Microsoft Power Automate.
2. Seleccione Crear en el menú lateral de la página.
3. Seleccione Flujo de nube automático en las opciones de Empezar desde cero.

   Aparece el cuadro de diálogo Crear un flujo de nube automático.

4. Ponga un nombre al flujo.

   A continuación, seleccionará un desencadenador.

5. Escriba ArcGIS en la barra de búsqueda y seleccione Cuando se crea un registro en una capa de entidades como desencadenante en este flujo de trabajo.
6. Haga clic en Crear.
7. Inicie sesión con las credenciales de su organización de ArcGIS y seleccione la capa de entidades que desea supervisar.

   Debe seleccionar la capa de entidades o la vista de capa de entidades a la que se envían los datos.

8. Agregue la acción Recuperar cambios, actualizaciones o eliminaciones de la acción de la capa de entidades a este flujo de trabajo.
   1. Defina Cambiar URL como entrada de Obtener cambios de.
   2. Defina layerId como el campo de entrada del Id. de la capa de entidades.
9. Elija Office 365 Outlook - Enviar un correo electrónico (V2).
10. Inicie sesión en el servicio de correo con sus credenciales, si es que aún no están guardadas.
11. Rellene los campos Para, Asunto y Cuerpo de su correo electrónico.

    El cuadro de diálogo Contenido dinámico que aparece cuando selecciona un cuadro de texto le permite insertar el contenido de la respuesta de encuesta según sus necesidades.

12. Cuando haya terminado el correo electrónico, haga clic en Guardar.

El webhook se completa y se activa de forma predeterminada. El webhook se ejecutará ahora cada 30 segundos.

Configurar un webhook de Survey123 en Microsoft Power Automate

Siga estos pasos para configurar un webhook de Survey123 en Microsoft Power Automate:

Nota:

Las credenciales de ArcGIS Online que se utilizan para crear flujos en Power Automate cierran la sesión de forma automática después de dos semanas. Si no puede examinar las encuestas esperadas en Power Automate, confirme que su conexión de datos con Survey123 está activa. Para obtener más información, consulte el artículo del blog Consejo rápido: Cómo mantener válido el token de actualización de ArcGIS Connectors for Power Automate.

Para configurar un flujo en Microsoft Power Automate utilizando los conectores de ArcGIS o ArcGIS Enterprise, siga los pasos que se indican a continuación. Si anteriormente creó flujos con el conector de Survey123, estos seguirán funcionando, pero la nueva funcionalidad solo se agregará a los conectores de ArcGIS y ArcGIS Enterprise. Para obtener más información, consulte el artículo del blog Desencadenadores y acciones de Survey123 en ArcGIS Connectors for Power Automate.

1. Abra Microsoft Power Automate.
2. Seleccione Crear en el menú lateral de la página.
3. Seleccione Flujo de nube automático en las opciones de Empezar desde cero.

   Aparece el cuadro de diálogo Crear un flujo de nube automático.

4. Ponga un nombre al flujo.

   A continuación, seleccionará un desencadenador.

5. Escriba ArcGIS en la barra de búsqueda y seleccione Cuando se envía la respuesta a una encuesta.
6. Haga clic en Crear.
7. Inicie sesión con las credenciales de su organización de ArcGIS.
8. Seleccione la encuesta que desee usar para el webhook en la lista desplegable de encuestas.

   Ya ha configurado el desencadenador para el webhook; sin embargo, para que el webhook realice acciones con este desencadenador, hay pasos adicionales.

   El flujo debe enviar un correo electrónico cuando se ha respondido a una pregunta de una forma concreta, de modo que indicará una condición.

9. Haga clic en el botón Nuevo paso y elija Condición en la parte superior de la sección Acciones.
10. Haga clic en el cuadro de texto que está más a la izquierda para abrir un cuadro de diálogo y elegir una pregunta o propiedad de la encuesta y seleccione la pregunta de la encuesta que desea usar para calificar la encuesta.
11. En el cuadro de texto central, en el menú desplegable, seleccione la condición es igual a como desencadenador, ya que está buscando una respuesta exacta.
12. En el cuadro de texto que está más a la derecha, escriba el valor de la pregunta para la que desee enviar una notificación.

    Usted desea que este correo electrónico solo se envíe si se cumple la condición.

13. Haga clic en Agregar una acción en el cuadro Si se cumple.

    El cuadro Si no se cumple permanece vacío.

    Varios servicios de correo disponen de conectores que se pueden utilizar para este flujo.

14. Elija Office 365 Outlook - Enviar un correo electrónico (V2).
15. Inicie sesión en el servicio de correo con sus credenciales, si es que aún no están guardadas.
16. Rellene los campos Para, Asunto y Cuerpo de su correo electrónico.

    El cuadro de diálogo Contenido dinámico que aparece cuando selecciona un cuadro de texto le permite insertar el contenido de la respuesta de encuesta según sus necesidades.

17. Cuando haya terminado el correo electrónico, haga clic en Guardar.

El webhook se completa y se activa de forma predeterminada. El webhook ahora se ejecutará cada vez que se envíe una respuesta de encuesta que reúna las condiciones definidas.

Sugerencia:

Puede utilizar el módulo Crear informe para generar un informe para una respuesta de encuesta

Configurar un webhook de Survey123 en Make

Siga estos pasos para configurar un webhook de Survey123 en Make:

1. Vaya a https://www.make.com/ e inicie sesión.
2. En la página Escenarios, haga clic en el botón Crea un nuevo escenario.
3. Haga clic en el icono de módulo del centro de la pantalla. Busque Survey123 y selecciónelo.

   

4. Elija el módulo desencadenador Ver encuesta.

   Este módulo se ha diseñado para ejecutar el escenario cada vez que se envíe una respuesta a una encuesta.

   Aparece un elemento emergente que le ayuda a configurar el módulo Ver encuesta.

   Sugerencia:

   Puede utilizar el módulo Crear informe para generar un informe para una respuesta de encuesta.

5. Haga clic en Agregar y proporcione un nombre para su webhook.

   Este nombre debe ser exclusivo de la encuesta para la cual está configurando el webhook.

6. Si esta es la primera vez que utiliza el módulo Survey123 en Make, establezca una conexión a su organización de ArcGIS. En Conexión, haga clic en Agregar y asigne un nombre a la conexión a ArcGIS.

   Solo necesita hacerlo una vez, dado que Make guardará su información para uso futuro.

   • Para conectarse a ArcGIS Online, haga clic en Guardar para iniciar sesión en su organización de ArcGIS.
   • Para conectarse a ArcGIS Enterprise, regístrese en Make con su portal. Para obtener más información, consulte el artículo de blog Secretos de Survey123: Make
7. Elija la encuesta de su organización de ArcGIS a la que desea conectarse.

   

8. Considere las opciones que desea incluir en su webhook y haga clic en Guardar.

   Se recomienda mantener el valor predeterminado Sí en todos los ajustes avanzados, ya que es lo que le proporciona la mayor flexibilidad a la hora de personalizar el webhook.

9. Haga clic en Aceptar.

   Se crea el webhook y se configura el módulo Ver encuesta.

10. Haga clic en el botón Agregar otro módulo en el lateral derecho del módulo Ver encuesta para conectarle otro módulo.

    

11. Busque Correo electrónico y seleccione el módulo Correo electrónico.
12. Seleccione la acción Enviar correo electrónico.
13. Si es la primera vez que utiliza este módulo en Make, haga clic en Agregar para configurar una conexión a su cuenta de correo electrónico. Seleccione un tipo de conexión e inicie sesión en su cuenta.

    Solo necesita hacerlo una vez, dado que Make guardará su conexión para uso futuro.

14. Agregue una dirección de correo electrónico de destinatario.

    Esta es la dirección de correo electrónico a la que se enviará el correo electrónico generado por el desencadenador.

15. Haga clic en el cuadro de texto de asunto. Elija campos de su encuesta para construir el asunto de su correo electrónico utilizando el panel de configuración del módulo que aparece.
16. Haga clic en el cuadro de texto de contenido. Elija campos de su encuesta para construir el contenido de su correo electrónico utilizando el panel de configuración del módulo que aparece.

    Puede formatear el contenido con HTML.

17. Haga clic en Aceptar.

    Este escenario debe enviar el correo electrónico cuando se ha respondido a una pregunta de una forma concreta, de modo que indicará un filtro.

18. Haga clic en el icono de las herramientas entre los dos módulos y seleccione Definir filtro.

    

19. Haga clic en el cuadro de texto Condición y elija el campo de su encuesta que desea usar en el filtro.

    

20. Elija el operador para la condición. En este caso, elija el predeterminado, Igual que.
21. Introduzca un valor para la condición y haga clic en Aceptar.
22. Haga clic en Guardar para guardar su escenario.

    Opcionalmente, puede hacer clic en Ejecutar una vez para probar su webhook. Después de hacer clic en Ejecutar una vez, abra Survey123 y envíe una encuesta, asegurándose de que la respuesta de la encuesta cumpla la condición de filtro. Confirme que el destinatario recibe el correo electrónico.

23. Utilice el botón de alternancia activar/desactivar de la parte inferior izquierda de la página para activar su escenario. Cambie la programación a Inmediatamente para asegurarse de que el escenario se ejecute cada vez que se envíe una respuesta a la encuesta.

    Para conocer más formas de utilizar Survey123 como desencadenador de escenarios de Make, consulte Integraciones de Survey123.

Agregar un webhook en el sitio web de Survey123

En el sitio web se puede agregar tanto un webhook de Survey123 como un webhook de capa de entidades. Los siguientes pasos muestran cómo configurar un webhook para una capa de entidades. El webhook de Survey123 es igual, pero incluye opciones adicionales de Datos del evento que se enumeran en Propiedades de la carga útil del evento.

1. En la página Mis encuestas, seleccione la pestaña Configuración en el menú de la parte inferior derecha del panel de la encuesta.
2. En el menú de la izquierda, seleccione la sección Webhook.

   Esta página le permite configurar y acceder a todos los webhooks que haya configurado. Si no ha configurado ningún webhook en Survey123, la página estará vacía.

3. Haga clic en Agregar webhook y seleccione Agregar webhook de capa de entidades.

   Aparece un nuevo panel donde puede configurar cómo interactuará el webhook con su encuesta.

4. Proporcione un nombre para su webhook, que se utilizará para identificar su webhook en el futuro.

La URL de carga es el lugar al que se enviará la información de la encuesta. Debe provenir de un servicio de webhooks externo. Cuando crea un webhook mediante un servicio como Microsoft Power Automate o Make, la URL de carga se completa automáticamente en esta página. Otros servicios, como Zapier o FME Server, proporcionan la URL de carga para que la copie en esta página. Otras aplicaciones pueden requerir que cree un servicio específico para escuchar el webhook.

Los eventos desencadenadores describen las acciones específicas que llamarán al webhook.

5. Seleccione Nuevo registro enviado.
El botón de alternancia Estado determina si el webhook estará activo al guardarlo.
6. Déjelo como Activado (el valor predeterminado).
7. Haga clic en Guardar.

El webhook está listo para su uso y se ejecutará cada vez que se envíe una respuesta de la encuesta. Las reglas definidas dentro del proveedor de webhooks pueden garantizar el envío de un correo electrónico solamente si se reúnen determinados criterios.

Propiedades de Carga de eventos

Un evento de webhook envía una carga de propiedades como un objeto JSON. El contenido de la carga variará en función del tipo de webhook utilizado y de la encuesta.

Los webhooks de las capas de entidades geográficas solo contienen eventos addData o editData. Para obtener más información, consulte Cargas de los webhooks de capas de entidades.

Los webhooks de Survey123 contienen el tipo de evento y propiedades adicionales. En la siguiente tabla se enumeran las propiedades comunes que contiene el objeto JSON de un webhook de Survey123:

Propiedad	Descripción
eventType	El tipo de modelo. Los valores pueden ser addData o editData.
portalInfo	Información sobre la organización de ArcGIS en la que se aloja la encuesta. Contiene las siguientes opciones: url token
surveyInfo	Información sobre la encuesta que generó el webhook. Contiene las siguientes opciones: formItemId formTitle serviceItemId serviceUrl
userInfo	Información sobre la cuenta de organización de ArcGIS para el usuario que ha enviado la encuesta. Contiene las siguientes opciones: username firstName lastName fullName email

Las siguientes propiedades de los webhooks de Survey123 variarán en función del tipo de encuesta y de evento:

Propiedad	Descripción
applyEdits	La carga Aplicar ediciones enviadas por la encuesta. Si eventType es addData, contendrá adds. Si eventType es editData, contendrá updates. Al agregar un nuevo registro de repetición, también contendrá adds.
response	La respuesta de la operación applyEdits. Incluye los Id. globales de las entidades creadas por la operación y si la operación se realizó correctamente.
feature	El registro de la encuesta que se envió. Contiene las siguientes opciones: attributes geometry layerInfo result repeats Nota: Cada objeto dentro del conjunto repeatses un feature que tiene attributes, geometry , layerInfo , result,repeatsattachments attachments id globalId name contentType size keywords url parentObjectId