Desencadenador de webhook

5 minutos

Los webhooks son implementaciones populares basadas en HTTP de un patrón de notificación editor-suscriptor más genérico. Ofrecen una forma de que las notificaciones se envíen a un servicio externo (suscriptor) cada vez que ocurren ciertos eventos dentro de un sistema (editor).

Power Automate y Azure Logic Apps permiten a los fabricantes utilizar webhooks como desencadenadores. En este escenario, los desencadenadores desempeñarán el papel de un suscriptor que registra y anula el registro de webhooks en nombre de un fabricante. El registro se produce cuando se crea o actualiza un paso en un flujo de nube o en un flujo de trabajo de Logic Apps. Cuando se elimina el paso, la plataforma anula el registro del webhook.

Como Copilot puede ayudarle a configurar el conector, también puede hacerlo en este caso. Puede comenzar con indicaciones sencillas y, a medida que avance, hacer que mejore su implementación:

"¿Cómo defino un desencadenador HTTP para mi conector personalizado?"
"¿Qué parámetros debo incluir en mi controlador de conector personalizado?"
"¿Pueden comprobar mi lógica de comprobador para ver posibles mejoras?"

Copilot puede sugerir la forma óptima de definir los desencadenadores según su API y los requisitos del flujo.

La siguiente captura de pantalla muestra un ejemplo de la interacción entre el suscriptor y el editor.

Las responsabilidades de las partes se resumen en la siguiente tabla.

Publicar (conector personalizado OpenAPI)	Suscriptor (Power Automate/Logic Apps)
Proporciona el punto de conexión de registro de la suscripción.	Llama al punto de conexión de registro de la suscripción cuando se crea o actualiza un desencadenador en un flujo.
Especifica el contrato de notificación, es decir, qué objeto se pasará con cada notificación. Debe incluir el encabezado HTTP Ubicación en la respuesta 201 en el momento en que se cree un webhook.	Proporciona la URL del punto de conexión generado automáticamente que aceptará los mensajes de notificación.
Mantiene el registro de suscriptores y sus puntos de conexión de notificación.	Recibe y almacena información de ubicación que se utilizará para cancelar el registro del webhook.
Emite una solicitud POST a cada punto de conexión registrado y pasa los datos relevantes en el cuerpo del mensaje.	Recibe notificaciones, las valida frente al esquema definido por el conector personalizado y luego desencadena la automatización.
Anula el registro o elimina los puntos de conexión en respuesta al mensaje DELETE.	Emite un mensaje DELETE para cancelar el registro del webhook cuando se elimina el paso del desencadenador.

Los webhooks solo proporcionan el mecanismo de notificación y no admiten la manipulación de los datos. A menudo, la implementación de un webhook se complementa con una o más acciones diseñadas para admitir la recuperación y manipulación de datos u objetos.

Requisitos de API

Para proporcionar el soporte de webhook que requieren los conectores personalizados, la implementación de las API debe proporcionar los siguientes parámetros:

Un punto de conexión que acepta el mensaje de registro y devuelve información de ubicación
Una definición del cuerpo del mensaje que se envía con los mensajes de notificación
Un punto de conexión para aceptar el mensaje DELETE para quitar el registro de webhook

Por lo general, la implementación de las API mantiene una lista interna de suscriptores activos, donde cada suscriptor se identifica mediante una URL única. Para devolver esta URL al suscriptor, se requiere la creación correcta del webhook para devolver una respuesta HTTP 201 e incluir un encabezado HTTP Ubicación. El suscriptor utilizará el valor de esta ubicación más adelante para eliminar el registro del webhook.

Crear un desencadenador de webhook

Los conectores personalizados usan OpenAPI para describir la implementación de la API del editor, según lo requieran los webhooks. Para definir un desencadenador de webhook en un conector personalizado, debe incluir tres partes esenciales en la definición de OpenAPI:

Un mensaje POST que describe el registro de webhook
Definición de contenido para las respuestas de webhook
Un mensaje DELETE que describe el proceso de eliminación de webhooks

Mensaje de registro

La definición del desencadenador debe incluir un método POST que se utilice para registrar un webhook. Se define de manera similar a las acciones.

La versión de la especificación de OpenAPI que utiliza Microsoft Power Platform no diferencia entre acciones y desencadenadores. La definición de conector personalizado utiliza la extensión personalizada x-ms-trigger para declarar un desencadenador.

paths:
  /webhooks:
    post:
      operationId: OrderCreated
      x-ms-trigger: single

La presencia de la extensión x-ms-trigger indica que el método es un desencadenador y no una acción. Cuando se crea un desencadenador mediante el asistente, esta extensión se agrega automáticamente. Sin embargo, cuando se crea un conector personalizado a partir de las definiciones de OpenAPI externas, el proceso de importación siempre crea acciones. En este escenario, debe volver a crear los desencadenadores mediante el asistente y luego eliminar las definiciones de acción correspondientes.

Los posibles valores para la extensión x-ms-trigger son único o lote para diferenciar entre respuestas de un objeto y de una matriz. Se incluye un único objeto cuando un webhook genera una notificación para cada cambio. Este enfoque es el más común con los webhooks. Cuando se combinan varios cambios en una sola notificación, se envía una matriz de objetos. Este enfoque se usa normalmente en los desencadenadores de sondeo y se tratará más adelante en el módulo.

Respuesta del webhook

Las definiciones de conectores personalizados pueden describir el contenido de las respuestas de webhook entrantes de su servicio cuando ocurre un evento. Si bien no es obligatorio, esta definición identifica los valores dinámicos que están disponibles para el creador en el momento del diseño en la lista de contenido dinámico.

Nota

Esta respuesta no es de la solicitud que crea y registra el webhook. Su servicio envía estos datos cuando ocurre un evento.

La propiedad personalizada x-ms-notification-content es otra extensión que se utiliza en OpenAPI para definir el esquema de respuesta de webhook.

paths:
  /webhooks:
    x-ms-notification-content:
      description: Order
      schema:
        type: object
        properties:
          id: {type: integer, format: int32, description: id}
          order_key: {type: string, description: order_key}
          status: {type: string, description: status}
          currency: {type: string, description: currency}
          date_created: {type: string, description: date_created}
          total: {type: number, description: total, format: decimal}

Sugerencia

Una definición de respuesta de webhook no necesita contener todo el contenido de la respuesta, solo las partes que desee exponer a los creadores de flujo en el momento del diseño en la lista de contenido dinámico.

Los datos que se envían con la respuesta del webhook no necesitan contener todas las propiedades que necesita del objeto subyacente, y es posible que no lo hagan. En estas situaciones, podría desear crear otras acciones en el conector personalizado para la recuperación de información. Por ejemplo, una tienda web solo puede enviar un nuevo identificador de pedido con la notificación "Cuando se crea un nuevo pedido". A continuación, el conector personalizado puede definir una acción, como "Obtener detalles del pedido", que acepta un identificador de pedido y devuelve información ampliada sobre el pedido.

El proceso inverso también es cierto. Las respuestas de webhook pueden proporcionar información excesiva que no se precisa o no es necesaria en circunstancias normales. Solo necesita describir los datos que desea mostrar en la interfaz del creador de Power Automate o Logic Apps. Si el creador necesita acceder a más datos que los que se envían en la notificación, puede usar funciones JSON para extraer directamente estas propiedades del mensaje recibido.

Eliminar mensaje

Para que Power Automate o Logic Apps eliminen un webhook, la API debe incluir un encabezado HTTP Ubicación en la respuesta, en el momento en que se crea el webhook.

Importante

Debe definir la ruta de la solicitud de eliminación de webhook como una acción interna. Esta acción enviará una solicitud DELETE a la URL que se especifica en el encabezado de la ubicación.

Si esta acción no está definida, o si la API no incluye el encabezado de ubicación, se crearán webhooks, pero no se eliminarán, lo que podría causar problemas en la implementación de la API en runtime.