Saltar al contenido

Ganchos Web

Descripción General

Vinyl admite la capacidad de invocar un evento en respuesta a un correo, mensaje de texto o una llamada API a un extremo de Vinyl mediante Webhooks. Los webhooks son devoluciones de llamadas HTTP definidas por el usuario y, por lo general, se activan mediante un evento. Cuando ocurre el evento especificado, el sitio de origen realiza una solicitud HTTP a la URL configurada para el webhook.

Un ejemplo de un Webhook en Vinyl es si una aplicación de Vinyl envía un correo a un usuario pidiéndole que apruebe o rechace una transferencia. El usuario respondería al correo escribiendo "aprobar" o "rechazar" en el cuerpo del mensaje. Si el usuario responde con "aprobar", Vinyl invoca un evento; "desaprobar", se invoca otro evento. Esta característica permite al usuario responder al correo o mensaje de texto sin salir de la aplicación.

Cómo Configurar un Webhook

En este ejemplo tenemos una aplicación Vinyl que se utiliza para la gestión de pedidos. El usuario desea poder crear un nuevo pedido mediante una llamada API y recibir el número de pedido en la respuesta de la API. El propósito del Webhook será generar un nuevo registro de Pedido, calcular el número de pedido y devolver ese número de pedido en la respuesta.

Nuestra tabla de pedidos tiene un ID de pedido (PK), nombre de la empresa, nombre del producto y número de pedido:

tabla de pedidos.png

Paso 1: Agregar Webhook en Servidores de Datos

  1. Crear servidor:

    • Navegue hasta IDE, Servidores de datos y haga clic en +Servidor
    • Asigne un Nombre de servidor. Por ejemplo: PedidoWebhook
    • Seleccione Tipo como API de webhook en servicios web
    • Elija el Contenido de tipo de contenido de solicitud/respuesta apropiado; en nuestro ejemplo, ambos son JSON.

    • Haga clic en Guardar y cierre la ventana emergente:

      orderdataserver.png

  2. Crear Extremo:

    • Haga clic en el botón Servidor de datos Detalles
    • Haga clic en el botón Extremos
    • Haga clic en + Extremo en el panel Extremos

    • Nombra tu extremo. Por ejemplo: publicar pedido

      Nota

      Este nombre no aparecerá en la URL del webhook.

    • Seleccione el Método HTTP que utiliza su Webhook. Normalmente será una POST para actualizar la información de una tabla.

    • Haga clic en el ícono marca de verificación para guardar

  3. Cree parámetros de Extremo:

    • Haga clic en Descubrir en el panel Extremos

    • Si el webhook acepta un cuerpo (p. ej., una POST que utiliza el tipo de contenido de solicitud JSON o XML), proporcione un Cuerpo de solicitud de muestra. Para nuestro ejemplo, nuestro JSON es:

      {
    "Company": "Jitterbit",
    "Product": "Vinyl"
}

      (Generaremos el ID de pedido y el Número de pedido como parte de los eventos desencadenados por el Webhook)

      webhookendpoint.png

    • Haga clic en Guardar

    • Haga clic en Descubrir. Esto agregará automáticamente los parámetros de Extremo de entrada.

  4. Si lo desea, agregue el parámetro extremo de respuesta. En nuestro ejemplo, sería del tipo Cadena, Longitud -1 caracteres, sin valor de prueba, sin tipo seleccionado para Cookie/Encabezado/Consulta y la Dirección es Salida.

Paso 2: Agregue Webhook a Su Aplicación

  1. Vaya a App Workbench > Fuentes de datos
  2. Haga clic en + Fuente
  3. Seleccione Enlace a fuente existente
  4. Haga clic en Siguiente
  5. Seleccione REST Webhook API configurado en el Paso 1
  6. Haga clic en el botón Enlace
  7. Revise el resumen de lo que realizará Vinyl y haga clic en Listo

Paso 3: Cree una Regla Comercial de Webhook

  1. Vaya a App Workbench > Reglas.
  2. Confirme que la Fuente de datos de la aplicación seleccionada sea la fuente de datos del Webhook recién creado y no la fuente de datos de la aplicación.

  3. Haga clic en + Regla

    appdatasources.png

  4. Asigne un Nombre. Por ejemplo: Pedido (Webhook)

  5. Seleccione Webhook como Propósito
  6. Seleccione la fuente de datos del webhook como Fuente de datos de origen
  7. Establezca Destino en el extremo del Webhook.
  8. Haga clic en Guardar
  9. Agregue su tabla Extremo y seleccione todas las columnas. En nuestro ejemplo, esta es la tabla PostOrder.

Paso 4: Cree Reglas Comerciales XP CRUD

Cree una regla comercial XP CRUD que inserte el valor recibido del Webhook en una tabla en la fuente de datos de su aplicación. Cree una regla comercial XP CRUD que inserte el valor recibido del Webhook en una tabla en la fuente de datos de su aplicación. Esto debe registrarse en la fuente de datos del Webhook como el objeto Webhook que acabamos de crear. Algunas notas:

  • La tabla de pedidos debe permitir la lectura/escritura pública, que se puede configurar en la configuración de Edge Case de la tabla de pedidos en el diseño de la tabla.
  • La capa de destino debe establecerse en Capa lógica

Agregaremos una columna para generar una PK usando el newuuid() funcione y agregue las columnas Empresa y Producto de nuestro objeto webhook con los objetivos apropiados:

pedidoxpcrud.png

xpcolumnas.png

Nota

No necesitamos agregar el número de pedido porque se genera como parte del evento Insertar de la tabla de pedidos.

Paso 5: Cree una Regla Comercial XP CRUD

Cree una regla comercial CRUD de XP que actualice y escriba una respuesta con el número de pedido del nuevo pedido.

  1. Cree una nueva regla CRUD de XP registrada en la fuente de datos del Webhook. Por ejemplo, PostOrder (Actualizar respuesta)
  2. Establezca la acción en Actualizar
  3. Fuente de datos de origen al origen de datos de su aplicación
  4. Origen de datos de destino a la fuente de datos de su webhook
  5. Establezca la capa de destino en Capa lógica
  6. Establezca el destino en su objeto Webhook. Por ejemplo, ordenar webhook
  7. Agregar tabla de pedidos desde la fuente de datos de la aplicación
  8. Agregue la columna OrderNumber dirigida a la columna Respuesta

  9. Agregue la cláusula Where que filtra según el pedido recién generado (utilizamos la función generada para recuperar el ID de pedido generado en este evento)

    postxpexample.png

Nota

La función generada devuelve una cadena, por lo que debemos convertir el ID de pedido como una cadena para que esto funcione.

Paso 6: Agregue las Reglas Comerciales CRUD Como Acciones

Agregue las dos reglas comerciales CRUD creadas al evento de inserción de capa de datos de la regla comercial Webhook.

insertar evento.png

Paso 7: Exponer Webhook al Mundo

Cree un Extremo para su aplicación. Es posible que esto ya se haya hecho para su aplicación.

  1. Navegue hasta Vinyl IDE > APIs REST (en Conectar) > Webhooks
  2. Haga clic en el botón Administrar Extremos
  3. Seleccione la aplicación para la que desea ingresar el valor del extremo. Por ejemplo: WebhookDocumentación.
  4. Haga clic en el icono de edición de lápiz de la aplicación que está configurando.
  5. Ingrese el valor del Extremo en el campo Extremo. Por ejemplo WebhookDoc
  6. Haga clic en continuar para guardar.
  7. Para configurar el objeto Webhook, desde el Panel Webhooks haga clic en +Webhook
  8. Seleccione su objeto Webhook. Seleccionará automáticamente un nombre de Extremo. Esta se convertirá en la parte del webhook de la URL del webhook.

  9. Haga clic en Guardar

    exposewebhook.png

Paso 8: Cree una Clave API para Que un Usuario Acceda a Este Webhook

Crearemos una clave API básica y se la asignaremos a un usuario para acceder a este Webhook. Esto se puede hacer una vez para un Usuario del Servicio o varias veces para usuarios individuales.

  1. Navegue hasta IDE, Proveedores de seguridad
  2. En Autenticación de usuario, cree un registro de tipo Autenticación básica HTTP si no existe ninguno. Si es así, puedes saltarte este paso.
  3. Vaya a IDE, Administración de usuarios
  4. Seleccione el Usuario que necesita una Clave
  5. En Autenticación, haga clic en Claves
  6. Haga clic en Crear
  7. Para Proveedor, seleccione el proveedor de seguridad de tipo Autenticación básica HTTP de los pasos 1 y 2.
  8. Haga clic en Guardar
  9. Anota el Identificador y la Clave generados, ya que esta información no volverá a estar disponible.

Paso 9: Prueba

Puedes probar este Webhook usando Postman o Insomnia. Envíe una llamada POST API con un cuerpo similar al ejemplo de cuerpo utilizado para crear los parámetros en el paso 1. Utilizará la autenticación básica con el identificador como nombre de usuario y la clave como contraseña del paso anterior.

Para realizar pruebas, utilice el enlace: https://<url>/webhook/v1/<application-endpoint>/<endpoint>

En el escenario donde no se requiere autenticación, en lugar de configurar una clave x-api en el encabezado, puede ajustar la URL a una de estas opciones:

  1. https://{{identificador del usuario del paso 8.9}}:{{clave de usuario del paso 8.9}}@{{url del paso 9}} (para usarse si el proveedor es de autenticación básica http sin parámetros)

    Precaución

    El método básico HTTP descrito anteriormente requiere que el encabezado de Autorización se incluya en la carga útil recibida. Para evitar esto, utilice el método de clave API.

  2. https://{{url del paso 9}}?apiKey={{clave de usuario del paso 8.9}} (se utilizará si el proveedor es una clave API y las propiedades incluyen HttpHeaderName 'X-API-Key')