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

  • Artículo

Webhooks son devoluciones de llamada HTTP simples que se utilizan para proporcionar notificaciones de eventos. Azure Logic Apps y Power Automate le permiten usar webhooks como desencadenadores. Una aplicación lógica o flujo escuchan este desencadenador y realizan una acción cada vez que se activa. Este tutorial muestra cómo usar un webhook como desencadenador.

Nota

Usaremos GitHub como ejemplo de servicio que puede enviar notificaciones a través de webhooks, pero las técnicas que se muestran a continuación se pueden extender a cualquier servicio que use webhook.

Requisitos previos

La definición de OpenAPI

Los webhooks se implementan en Logic Apps y Power Automate como parte de un conector personalizado, por lo que deberá proporcionar una definición de OpenAPI que defina la forma del webhook. Si desea crear un desencadenador, pero no tiene una definición de OpenAPI, puede utilizar desencadenar la interfaz de usuario en el asistente de conector personalizado para definir desencadenadores de webhook.

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

  • Creación de webhook
  • Definición de la solicitud de enlace entrante desde la API (en este caso, GitHub)
  • Eliminación de webhook

Creación de webhook

Una solicitud HTTP POST a /repos/{owner}/{repo}/hooks crea el webhook en el lado de GitHub. Cuando se crea una nueva aplicación lógica o flujo, se publica en esta URL mediante el desencadenador definido en la definición de OpenAPI. También se publica en la URL si se modifica el desencadenador. En el ejemplo siguiente, la propiedad post contiene el esquema de la solicitud que se publica en 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"
        }
        }
    }
    }
},

Importante

La propiedad "x-ms-trigger": "single" es una extensión de esquema que indica a Logic Apps y Power Automate que deben mostrar este webhook en la lista de los desencadenadores disponibles del diseñador. Por este motivo, asegúrese de incluirlo.

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

La forma de la solicitud de enlace de entrada (la notificación de GitHub a Logic Apps o Power Automate) viene definida en la propiedad x-ms-notification-content personalizada, como se muestra en el ejemplo anterior. No necesita incluir todo el contenido de la solicitud, solo las partes que desee usar en la aplicación lógica o flujo.

Eliminar el webhook

La definición de OpenAPI debe incluir una definición sobre cómo eliminar el webhook. Logic Apps y Power Automate intentarán eliminar el webhook si actualiza el desencadenador y si se elimina la aplicación lógica o 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 Hook being deleted",
        "required": true,
        "type": "string"
        }
    ]
    }
},

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

Importante

Para que Logic Apps o Power Automate eliminen un webhook, la API debe incluir un encabezado HTTP Location en la respuesta 201 en el momento en que se crea el webhook. El encabezado Location debe contener la ruta de acceso al webhook que se usa con HTTP DELETE. Por ejemplo, el valor de Location incluido con la respuesta de GitHub tendrá este formato: https://api.github.com/repos/<user name>/<repo name>/hooks/<hook ID>.

Habilitar la autenticación en GitHub

La API que envía la 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; utilizaremos tokens de acceso personal de GitHub para este tutorial.

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

  2. En la esquina superior derecha, seleccione la imagen de su perfil y, en el menú, elija Configuración.

    Configuración

  3. En el menú de la izquierda, elija Configuración de desarrollador y seleccione Tokens de acceso personal.

  4. Elija el botón Generar nuevo token y luego confirme su contraseña si se le solicita.

    Generar token

  5. En el cuadro Descripción de token, escriba una descripción.

  6. Seleccione la casilla admin:repo_hook.

    admin:repo_hook

  7. Elija el botón Generar token.

  8. Tome nota de su nuevo token.

    Nuevo token

    Importante

    No podrá volver a acceder a este token. Debe copiarlo y pegarlo en algún lugar para usarlo más adelante en el tutorial.

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, elija Conector de Logic Apps y elija Editar.

    Editar el conector de Logic Apps

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

    Captura de pantalla que muestra la opción Cargar un archivo OpenAPI.

Importar la definición de OpenAPI para Power Automate

  1. Vaya a flow.microsoft.com.

  2. En la esquina superior derecha, elija el icono de engranaje y después Conectores personalizados.

    Conectores personalizados

  3. Elija Crear conector personalizado y, a continuación, Importar una colección de Postman.

    Crear conector personalizado

  4. Escriba un nombre para el conector personalizado, navegue al archivo de OpenAPI que descargó y elija Conectar.

    Captura de pantalla que muestra el campo para escribir un nombre.

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

Terminar de crear el conector personalizado

  1. En la página General, elija 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. Son únicamente etiquetas que se mostrarán cuando se use el desencadenador en un flujo o aplicación lógica.

    Autenticación básica

  4. En la parte superior del asistente, asegúrese de que el nombre se establece en "GitHubDemo" y, después, seleccione 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, le mostraremos cómo 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 que especifica una descripción y una URL.

    Parámetro Value
    Descripción "GitHub es un repositorio de código fuente social".
    Dirección 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 disparador y complete la descripción del desencadenador. En este ejemplo, vamos a crear un desencadenador que se activa cuando se realiza una solicitud de extracción en un repositorio.

    Crear Trigger-1

    Parámetro Value
    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:

    • Ninguna: normalmente se muestra 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.

    Página Definición: importar desde ejemplo

  5. Defina la solicitud para el desencadenador de webhook y, a continuación, elija Importar. Proporcionamos una muestra para que la importe (debajo de la imagen). Para obtener más información, consulte Referencia de API de GitHub. Logic Apps y Power Automate agregan automáticamente encabezados de seguridad y content-type estándar, por lo que no es necesario que los defina al importar desde un ejemplo.

    Crear Trigger-2

    Parámetro Value
    Verbo "POST"
    Dirección 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. Elija Agregar respuesta predeterminada.

    Página Definición: respuesta

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

    Crear Trigger-3

    {
  "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 de desencadenador, seleccione el parámetro que debe recibir el valor de URL de devolución de llamada de GitHub. Es la propiedad url del objeto config.

    Crear Trigger-4

  9. En la parte superior del asistente, ingrese un nombre, luego elija Crear conector.

Usar el webhook como desencadenador

Ahora que ya se ha configurado todo, puede utilizar el webhook en una aplicación lógica o flujo. A continuación, puede crear un flujo que envíe una notificación push a la aplicación móvil de Power Automate cada vez que el repositorio de GitHub reciba una inserción de git.

  1. En flow.microsoft.com, en la parte superior de la página, elija Mis flujos.

  2. Elija Crear desde cero, luego en la página siguiente, elija Buscar cientos de conectores y desencadenadores.

    Conectores de búsqueda

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

    Nuevo desencadenador

    Elija el elemento de la lista para usarlo como un desencadenador.

  4. Puesto que es la primera vez que ha usado este conector personalizado, tiene que conectarse a él. Ingrese la información de conexión, luego elija Crear.

    Nueva conexión

    Parámetro Value
    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

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

    Información del repositorio

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

    Importante

    Debe usar un repositorio para el que su cuenta tenga derechos. La manera más fácil de hacerlo sería utilizar su propio repositorio.

  6. Elija +Nuevo paso y después seleccione Agregar una acción.

  7. Busque y seleccione la acción Notificación de inserción.

    Notificación de inserción

  8. Ingrese texto en el campo Texto y los otros campos, utilizando los valores del cuadro de diálogo de contenido dinámico. Tenga en cuenta que estos valores provienen del objeto WebhookPushResponse del archivo OpenAPI.

    Detalles de la notificación de inserción

    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

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

    Nombre de flujo

Comprobación y solución de problemas

Para comprobar que todo está configurado correctamente, haga clic en Mis flujos y elija el icono de información situado al lado del 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. Esto indica que el webhook se creó correctamente en el lado de GitHub.

  • Si se produce un error en la ejecución, puede consultar los detalles de ejecución para ver por qué se produjo el error. Si el error se debió a una respuesta "404 no encontrado", es probable que su cuenta de GitHub no tenga los permisos correctos para crear un webhook en el repositorio que ha utilizado.

Resumen

Si todo está configurado correctamente, ahora recibirá notificaciones de inserción en la aplicación móvil de Power Automate siempre que se produzca una inserción de git en el repositorio de GitHub que seleccionó. Mediante el proceso anterior puede usar cualquier servicio compatible con webhook como desencadenador en los flujos.

Pasos siguientes

Proporcionar comentarios

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