Saltar al contenido

Webhooks

Descripción General

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

Un ejemplo de un Webhook en App Builder es si an App Builder la aplicación envía un correo a un usuario para solicitarle que apruebe o rechace una transferencia. El usuario respondería al correo, escribiendo "aprobar" o "desaprobar" en el cuerpo del mensaje. Si el usuario responde con "aprobar", App Builder invoca un evento; "desaprobar", se invoca otro evento. Esta función 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 an App Builder aplicación que se utiliza para la gestión de pedidos. El usuario desea poder crear un nuevo pedido a través de una llamada a la 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:

tabladepedidos.png

Paso 1: Agregar Webhook en Servidores de Datos

  1. Crear servidor:

    • Vaya a IDE, Servidores de datos y haga clic en +Servidor
    • Asignar un Nombre de servidor. Por ejemplo: OrderWebhook
    • Seleccione el tipo como Webhook API en los servicios web
    • Elija el Tipo de contenido de solicitud/respuesta apropiado; en nuestro ejemplo, ambos son JSON

    • Haga clic en Guardar y cierre la ventana emergente:

      servidordedatosdepedidos.png

  2. Crear Extremo:

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

    • Nombra tu extremo. Por ejemplo: PostOrder

      Nota

      Este nombre no aparecerá en la URL del webhook.

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

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

  3. Crear parámetros de Extremo:

    • Haga clic en Descubrir en el panel Extremos

    • Si el webhook acepta un cuerpo (por ejemplo, un 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": "App Builder"
}

      (Generaremos el OrderID y el OrderNumber como parte de los eventos activados 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 de extremo de respuesta. En nuestro ejemplo, sería de tipo cadena, con una longitud de -1 caracteres, sin ningún valor de prueba, sin ningún tipo seleccionado para Cookie/Encabezado/Consulta y la dirección sería Salida.

Paso 2: Agrega un Webhook a Tu 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 la API REST Webhook configurada en el Paso 1
  6. Haga clic en el botón Enlace
  7. Revisar el resumen de lo que App Builder se ejecutará y haga clic en Listo

Paso 3: Crear una Regla de Negocio de Webhook

  1. Vaya a App Workbench > Rules.
  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 + Rule

    appdatasources.png

  4. Asigna 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 Target en el extremo del webhook
  8. Haga clic en Guardar
  9. Agregue la tabla Extremo y seleccione todas las columnas. En nuestro ejemplo, se trata de la tabla PostOrder.

Paso 4: Crear Reglas de Negocio CRUD XP

Cree una regla de negocio CRUD de XP que inserte el valor recibido del webhook en una tabla en la fuente de datos de su aplicación.Cree una regla de negocio CRUD de XP 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 casos extremos de la tabla de pedidos en el diseño de la tabla
  • La capa de destino debe configurarse en la capa lógica

Agregaremos una columna para generar una clave primaria utilizando la newuuid() Función y agrega las columnas Empresa y Producto desde nuestro objeto webhook con los destinos apropiados:

orderxpcrud.png

xpcolumns.png

Nota

No necesitamos agregar el número de pedido porque este se genera como parte del evento de inserción de la tabla de pedidos

Paso 5: Crear una Regla de Negocio CRUD XP

Cree una regla de negocios 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 en la fuente de datos de su aplicación
  4. Fuente de datos de destino en la fuente de datos de su webhook
  5. Establezca la capa de destino en Capa lógica
  6. Establezca el destino en su objeto de webhook. Por ejemplo, Webhook de pedidos
  7. Agregue la tabla de pedidos desde la fuente de datos de la aplicación
  8. Agregue la columna de número de pedido que tenga como destino la columna de respuesta

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

    postxpexample.png

Nota

La función generada devuelve una cadena, por lo que debemos convertir el OrderID en una cadena para que esto funcione.

Paso 6: Agregue las Reglas de Negocio CRUD Como Acciones

Agregue las dos reglas de negocio CRUD creadas al evento de inserción de la capa lógica de la regla de negocio del webhook.

insertevent.png

Paso 7: Exponer el 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 App Builder IDE > APIs REST (en Conectar) > Webhooks
  2. Haga clic en el botón Administrar Extremos
  3. Seleccione la aplicación para la que desea introducir el valor del extremo. Por ejemplo: WebhookDocumentation.
  4. Haga clic en el ícono de edición de lápiz para la aplicación que está configurando
  5. Introduzca 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 de Webhooks haga clic en +Webhook
  8. Seleccione su objeto de webhook. Se seleccionará automáticamente un nombre de Extremo. Este se convertirá en la parte del webhook de la URL del webhook.

  9. Haga clic en Guardar

    exposewebhook.png

Paso 8: Crea 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 que acceda a este webhook. Esto se puede hacer una vez para un usuario del servicio o varias veces para usuarios individuales.

  1. Vaya a IDE, Proveedores de seguridad
  2. En Autenticación de usuario, cree un registro de tipo Autenticación básica HTTP si no existe. Si existe, puede omitir 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. Anote el Identificador y la Clave generados, ya que esta información no estará disponible nuevamente.

Paso 9: Prueba

Puede probar este Webhook con Postman o Insomnia. Envíe una llamada a la API POST 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 potencialmente la URL a una de estas opciones:

  1. https://{{Identificador del usuario del paso 8.9}}:{{clave del usuario del paso 8.9}}@{{URL del paso 9}}(para utilizar si el proveedor es 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 del usuario del paso 8.9}} (para utilizar si el proveedor es API Key y las Propiedades incluyen HttpHeaderName 'X-API-Key')