Uso de un webhook como desencadenador de Azure Logic Apps y Power Automate

Los webhooks son sencillas llamadas de retorno HTTP que proporcionan notificaciones de eventos cuando ocurre algo en un servicio web. En Azure Logic Apps y Power Automate puede usar webhooks como desencadenadores. Una aplicación lógica o flujo espera este desencadenante y realiza una acción cada vez que se activa. En este tutorial se muestra cómo usar un webhook como desencadenador a través de un conector personalizado definido con una especificación de OpenAPI.

Requisitos previos

• Una de las siguientes suscripciones:
  • Azure, si está utilizando Logic Apps
  • Power Automate
• Experiencia básica en la creación de aplicaciones lógicas o flujos en la nube y creación de conectores personalizados a partir de definiciones de OpenAPI.
• Si usa Logic Apps, cree un conector personalizado de Azure Logic Apps en primer lugar.
• Comprensión básica de webhooks.
• Comprensión básica de la Especificación OpenAPI (anteriormente conocido como Swagger).
• Una cuenta de GitHub.
• La definición de OpenAPI de ejemplo para este tutorial. Si aún no lo tiene, descárguelo para usarlo en los pasos siguientes. De lo contrario, debe crear una definición personalizada de OpenAPI para el webhook.

Habilitar la autenticación en GitHub

Una API de servicio web que envía una solicitud de webhook a Logic Apps o Power Automate normalmente usa algún tipo de autenticación y GitHub no es ninguna excepción. GitHub admite varios tipos de autenticación. En este tutorial se usan tokens de acceso personal de GitHub de granularidad fina.

1. Vaya a GitHub e inicie sesión si aún no lo ha hecho.

2. En la esquina superior derecha, seleccione la imagen del perfil y, después, en el menú, seleccione Configuración.

3. En el menú de la izquierda, seleccione Configuración de desarrollador.

4. En Tokens de acceso personal, seleccione Tokens específicos.

5. Seleccione el botón Generar nuevo token y confirme la contraseña si se solicita.

6. Escriba un nombre de token y una descripción para el token.

7. En Expiración, seleccione una fecha de expiración para el token.

8. En Acceso al repositorio, seleccione Solo repositorios y seleccione el repositorio al que desea conceder acceso.

9. En Permisos, seleccione Agregar permisos>Webhooks>Lectura y escritura.

10. Seleccione el botón Generar token .

11. Tome nota de su nuevo token. Debe usar este token más adelante al agregar el conector de webhook como desencadenador.

    Importante

    No puede acceder a este token de nuevo. Copie y péguelo en algún lugar para usarlo más adelante en el tutorial.

Definición del webhook en la definición de OpenAPI

Puede implementar webhooks en Logic Apps y Power Automate como parte de un conector personalizado. Para crear el conector, debe proporcionar una definición de OpenAPI que defina la forma del webhook. En este tutorial se usa una definición de OpenAPI de ejemplo descargada para GitHub webhooks.

Si desea crear un desencadenador, pero no tiene una definición de OpenAPI desde la que trabajar, use la interfaz de usuario de desencadenadores en el Asistente para conectores personalizados para definir desencadenadores de webhook.

La definición de OpenAPI de ejemplo contiene tres partes que son fundamentales para hacer que el webhook funcione:

• Creación del webhook
• Definición de la solicitud de enlace entrante desde la API de servicio web (en este ejemplo de tutorial, GitHub)
• Eliminar el webhook

El conector usa esta definición de OpenAPI para comprender cómo crear, recibir y eliminar webhooks para el repositorio de GitHub.

Creación del webhook

El conector usa la API de servicio web (en nuestro ejemplo, la API rest de GitHub) para crear el webhook en el lado del servicio web enviando una solicitud HTTP POST al punto de conexión de creación de webhook adecuado para el servicio web (/repos/{owner}/{repo}/hooks en el caso de GitHub).

Al crear una nueva aplicación lógica o flujo mediante el conector, el conector envía una solicitud POST al extremo de creación del webhook del servicio web, tal como se define en la especificación OpenAPI del conector. También envía una solicitud POST a esta dirección URL si modifica la aplicación lógica o el desencadenador de flujo. En la siguiente configuración de ruta de OpenAPI de ejemplo, la propiedad post contiene el esquema de la solicitud para crear un webhook que se enviará a la API REST de GitHub.

"/repos/{owner}/{repo}/hooks": {
    "x-ms-notification-content": {
        "description": "Details for Webhook",
        "schema": {
            "$ref": "#/definitions/WebhookPushResponse"
        }
    },
    "post": {
        "description": "Creates a GitHub webhook",
        "summary": "Triggers when a PUSH event occurs",
        "operationId": "webhook-trigger",
        "x-ms-trigger": "single",
        "parameters": [
            {
            "name": "owner",
            "in": "path",
            "description": "Name of the owner of targeted repository",
            "required": true,
            "type": "string"
            },
            {
            "name": "repo",
            "in": "path",
            "description": "Name of the repository",
            "required": true,
            "type": "string"
            },
            {
            "name": "Request body of webhook",
            "in": "body",
            "description": "This is the request body of the Webhook",
            "schema": {
                "$ref": "#/definitions/WebhookRequestBody"
            }
            }
        ],
        "responses": {
            "201": {
            "description": "Created",
            "schema": {
                "$ref": "#/definitions/WebhookCreationResponse"
                }
            }
        }
    }
},

Definir la solicitud de enlace entrante a través de la API

Defina la forma de la solicitud de enlace entrante (la notificación de GitHub a Logic Apps o Power Automate) en la propiedad personalizadax-ms-notification-content, como se muestra en el ejemplo anterior. La solicitud no necesita contener todo el contenido de la solicitud, solo las partes que desea usar en la aplicación lógica o el flujo.

Eliminar el webhook

Incluya una definición para eliminar el webhook en la definición de OpenAPI. Logic Apps y Power Automate intentan eliminar el webhook existente si actualiza el desencadenador o si elimina la aplicación lógica o el flujo.

"/repos/{owner}/{repo}/hooks/{hook_Id}": {
    "delete": {
        "description": "Deletes a Github webhook",
        "operationId": "DeleteTrigger",
        "parameters": [
            {
                "name": "owner",
                "in": "path",
                "description": "Name of the owner of targeted repository",
                "required": true,
                "type": "string"
            },
            {
                "name": "repo",
                "in": "path",
                "description": "Name of the repository",
                "required": true,
                "type": "string"
            },
            {
                "name": "hook_Id",
                "in": "path",
                "description": "ID of the webhook being deleted",
                "required": true,
                "type": "string"
            }
        ]
    }
},

No se incluye ningún encabezado en la llamada para eliminar el webhook. La llamada de eliminación del webhook usa la misma conexión que el conector.

Importar la definición de OpenAPI

Comience por importar la definición de OpenAPI para Logic Apps o para Power Automate.

Importar la definición de OpenAPI para Logic Apps

1. Vaya a Azure Portal y abra el conector de Logic Apps que creó anteriormente en Creación de un conector personalizado de Azure Logic Apps.

2. En el menú de su conector, seleccione Conector de Logic Apps y, después, Editar.

   

3. En General, seleccione Cargar un archivo OpenAPI y, a continuación, vaya al archivo openAPI de ejemplo que descargó.

   

Importar la definición de OpenAPI para Power Automate

1. Ir a https://make.powerautomate.com/.

2. En la esquina superior derecha, seleccione el icono de engranaje y, a continuación, seleccione Conectores personalizados.

   

3. Seleccione Crear conector personalizado y, después, importar una colección de Postman.

   

4. Escriba un nombre para el conector personalizado, vaya al archivo OpenAPI de ejemplo que descargó y seleccione Conectar.

   

   Parámetro	valor
   Título de conector personalizado	"GitHubDemo"

Terminar de crear el conector personalizado

1. En la página General , seleccione Continuar.

2. En la página Seguridad, bajo Tipo de autenticación, seleccione Autenticación básica.

3. En la sección Autenticación básica, para los campos de etiqueta, escriba el texto Nombre de usuario y Contraseña. Estas etiquetas aparecen cuando se usa el desencadenador en una aplicación lógica o flujo.

   

4. En la parte superior del asistente, asegúrese de que el nombre esté establecido en "GitHubDemo" y, a continuación, elija Crear conector.

Ahora está listo para usar el desencadenador en una aplicación lógica o flujo, o bien puede leer cómo crear desencadenadores desde la interfaz de usuario.

Crear desencadenadores de webhook desde la interfaz de usuario

En esta sección, aprenderá a crear un desencadenador en la interfaz de usuario sin tener ninguna definición de desencadenador en la definición de OpenAPI. Comience con una definición de línea de base de OpenAPI o comience desde cero en el asistente de conector personalizado.

1. En la página General , asegúrese de especificar una descripción y una dirección URL.

   Parámetro	valor
   Descripción	"GitHub es un repositorio de código fuente social".
   URL	"api.github.com"

2. En la página Seguridad, configure la autenticación básica como lo hizo en la sección anterior.

3. En la página Definición , elija Nuevo desencadenador y rellene la descripción del desencadenador. En este ejemplo, estás creando un activador que se activa cuando se crea una pull request en un repositorio.

   

   Parámetro	valor
   Resumen	"Se desencadena cuando se realiza una solicitud de extracción en un repositorio seleccionado"
   Descripción	"Se desencadena cuando se realiza una solicitud de extracción en un repositorio seleccionado"
   Id. de operación	"webhook-PR-trigger"
   Visibilidad	"ninguno" (para obtener más información, vea a continuación)
   Tipo de desencadenador	"Webhook"

   La propiedad Visibilidad para operaciones y parámetros en una aplicación lógica o flujo tiene las siguientes opciones:

   • ninguno: se muestra normalmente en la aplicación lógica o el flujo
   • avanzada: oculta en un menú adicional
   • interna: oculta al usuario
   • Importante: se muestra siempre primero al usuario

4. El área Solicitud muestra información basada en la solicitud HTTP de la acción. elija Importar desde ejemplo.

   

5. Defina la solicitud para el desencadenador de webhook y, a continuación, seleccione Importar. Proporcionamos un ejemplo para importarlo (en la sección siguiente). Para obtener más información, consulte Referencia de API de GitHub. Logic Apps y Power Automate agregan automáticamente encabezados estándar content-type y de seguridad, por lo que no es necesario definirlos al importar desde un ejemplo.

   

   Parámetro	valor
   Verbo	"POST"
   URL	"https://api.github.com/repos/{owner}/{repo}/hooks"
   Cuerpo	Consulte a continuación

   {
     "name": "web",
     "active": true,
     "events": [
       "pull_request"
     ],
     "config": {
       "url": "http://example.com/webhook"
     }
   }
   

6. El área Respuesta muestra información basada en la respuesta HTTP de la acción. Seleccione Agregar respuesta predeterminada.

   

7. Defina la respuesta para el desencadenador de webhook y, a continuación, seleccione Importar. De nuevo, proporcionamos una muestra para que la importe. Para obtener más información, consulte Referencia de API de GitHub.

   

   {
     "action": "opened",
     "number": 1,
     "pull_request": {
       "html_url": "https://github.com/baxterthehacker/public-repo/pull/1",
       "state": "open",
       "locked": false,
       "title": "Update the README with new information",
       "user": {
         "login": "baxterthehacker",
         "type": "User"
       }
     }
   }
   

8. En el área Configuración del desencadenador, seleccione el parámetro que debe recibir el valor de la URL de devolución de llamada de GitHub. Este parámetro es la url propiedad del config objeto .

   

9. En la parte superior del asistente, escriba un nombre y elija Crear conector.

Usar el webhook como desencadenador

Después de configurar todo, use el webhook a través del conector personalizado en una aplicación lógica o un flujo. A continuación, cree un flujo que envíe un correo electrónico cada vez que el repositorio de GitHub reciba una inserción de Git.

1. En https://make.powerautomate.com/, en la parte superior de la página, seleccione Mis flujos.

2. Seleccione Crear en blanco.

   

3. En el diseñador de Power Automate, busque el conector personalizado que ha registrado anteriormente.

   

4. Seleccione el elemento de la lista para usarlo como desencadenador.

5. Como es la primera vez que ha usado este conector personalizado, conéctese a él. Escriba la información de conexión y, a continuación, seleccione Crear.

   

   Parámetro	valor
   Nombre de conexión	Un nombre descriptivo
   Nombre de usuario	Su nombre de usuario de GitHub
   Contraseña:	El token de acceso personal que creó anteriormente

6. Escriba los detalles sobre el repositorio que desea supervisar. Es posible que reconozca los campos del objeto WebhookRequestBody en el archivo de OpenAPI.

   

   Parámetro	valor
   propietario	El propietario del repositorio a supervisar
   repo	El repositorio para monitorear

   Importante

   Use un repositorio al que su cuenta tenga derechos. La manera más fácil de hacerlo es usar su propio repositorio.

7. Seleccione Nuevo paso>Agregar una acción.

8. Busque y seleccione la acción Enviar un correo electrónico (V2).

9. Escriba texto en el campo Cuerpo y los demás campos mediante valores del cuadro de diálogo contenido dinámico. Los valores proceden del objeto WebhookPushResponse en el archivo OpenAPI.

10. En la parte superior de la página, asigne un nombre al flujo y elija Crear flujo.

    

Comprobación y solución de problemas

Para comprobar que todo está configurado correctamente, seleccione Mis flujos y, a continuación, seleccione el icono de información situado junto al nuevo flujo para ver el historial de ejecución:

• Ya debería ver al menos una ejecución correcta desde la creación del webhook. Esta ejecución indica que el webhook se creó correctamente en el lado GitHub.
• Si se produjo un error en la ejecución, revise los detalles de la ejecución para ver por qué se produjo un error. Si el error se debió a una respuesta 404 Not Found, es probable que tu cuenta de GitHub no tenga los permisos adecuados para crear un webhook en el repositorio que utilizaste.

Resumen

Si ha configurado todo correctamente, recibirá notificaciones push en la aplicación móvil Power Automate cada vez que se produzca una inserción de Git en el repositorio de GitHub que seleccionó. Al usar el proceso anterior, puede usar cualquier servicio que admita webhooks como desencadenador en sus flujos.

Pasos siguientes

• Crear un conector personalizado para una API web
• Autenticar su API y conector con Microsoft Entra ID

Proporcionar comentarios

Agradecemos enormemente los comentarios sobre problemas con nuestra plataforma de conectores o nuevas ideas de funciones. Para enviar comentarios, vaya a Enviar problemas u obtener ayuda con los conectores y seleccione el tipo de comentario.