Saltar al contenido

Webhooks en Jitterbit App Builder

Descripción general

App Builder admite la capacidad de invocar un evento en respuesta a un correo electrónico, mensaje de texto o una llamada API a un endpoint de App Builder utilizando Webhooks. Los Webhooks son callbacks HTTP definidos por el usuario y, por lo general, se activan por 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 App Builder es si una aplicación de App Builder envía un correo electrónico a un usuario pidiéndole que apruebe o rechace una transferencia. El usuario respondería al correo electrónico, escribiendo "aprobar" o "rechazar" en el cuerpo del mensaje. Si el usuario responde con "aprobar", App Builder invoca un evento; "rechazar", se invoca otro evento. Esta función permite al usuario responder al correo electrónico o mensaje de texto sin salir de la aplicación.

Cómo configurar un webhook

En este ejemplo, tenemos una aplicación de App Builder que se utiliza para la gestión de pedidos. El usuario desea poder crear un nuevo pedido a través de 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 OrderID (PK), nombre de la empresa, nombre del producto y OrderNumber:

ordertable.png

Paso 1: Agregar webhook en servidores de datos

  1. Crear Servidor:

    • Navegar a IDE, Servidores de Datos y hacer clic en +Servidor
    • Asignar un Nombre de Servidor. Por ejemplo: OrderWebhook
    • Seleccionar Tipo como Webhook API bajo servicios web
    • Elegir el tipo de contenido de Solicitud/Respuesta apropiado, en nuestro ejemplo ambos son JSON

    • Hacer clic en Guardar y cerrar el popup:

      orderdataserver.png

  2. Crear Endpoint:

    • Hacer clic en el botón Detalles del Servidor de Datos
    • Hacer clic en el botón Endpoints
    • Hacer clic en +Endpoint en el panel de Endpoints

    • Nombrar su endpoint. Por ejemplo: PostOrder

      Nota

      Este nombre no aparecerá en la URL del Webhook.

    • Selecciona el Método HTTP que utiliza tu Webhook. Típicamente, esto será un POST para actualizar información en una tabla.

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

  3. Crea Parámetros de Endpoint:

    • Haz clic en Descubrir desde el panel de Endpoints.

    • Si el Webhook acepta un cuerpo (por ejemplo, un POST usando JSON o tipo de contenido XML Request), proporciona un Cuerpo de Solicitud de ejemplo. Para nuestro ejemplo, nuestro JSON es:

      {
    "Company": "Jitterbit",
    "Product": "App Builder"
}

      (Generaremos el OrderID y OrderNumber como parte de los eventos desencadenados por el Webhook)

      webhookendpoint.png

    • Haz clic en Guardar.

    • Haz clic en Descubrir. Esto añadirá automáticamente los Parámetros de Endpoint de entrada.

  4. Si lo deseas, añade el parámetro de endpoint de Respuesta. En nuestro ejemplo, sería de tipo String, Longitud -1 caracteres, sin valor de prueba, sin tipo seleccionado para Cookie/Header/Query, y la Dirección es Salida.

Paso 2: Agregar webhook a tu aplicación

  1. Navega a App Workbench > Fuentes de Datos.
  2. Haz clic en + Fuente.
  3. Selecciona Vincular a fuente existente.
  4. Haz clic en Siguiente.
  5. Selecciona la API Webhook REST configurada en el Paso 1.
  6. Haz clic en el botón Vincular.
  7. Revisa el resumen de lo que realizará App Builder y haz clic en Listo.

Paso 3: Crear una regla de negocio de webhook

  1. Navega a App Workbench > Reglas.
  2. Confirma que la Fuente de Datos de la Aplicación seleccionada sea tu nueva fuente de datos Webhook y no tu fuente de datos de aplicación.

  3. Haz clic en + Regla.

    appdatasources.png

  4. Asigna un Nombre. Por ejemplo: Orden (Webhook).

  5. Selecciona Webhook como Propósito.
  6. Selecciona la Fuente de Datos Webhook como Fuente de Datos.
  7. Establece Destino en el endpoint del Webhook.
  8. Haz clic en Guardar.
  9. Añade tu tabla de Endpoint y selecciona todas las columnas. En nuestro ejemplo, esta es la tabla PostOrder.

Paso 4: Crear reglas de negocio XP CRUD

Crea una regla de negocio XP CRUD que inserte el valor recibido del Webhook en una tabla en la fuente de datos de tu aplicación. Crea una regla de negocio XP CRUD que inserte el valor recibido del Webhook en una tabla en la fuente de datos de tu aplicación. Esto debe estar registrado en la fuente de datos del Webhook como el objeto Webhook que acabamos de crear. Algunas notas:

  • La tabla de pedidos debe permitir lectura/escritura pública, lo cual es configurable en la configuración de casos extremos de la tabla de pedidos en el diseño de la tabla.
  • La capa de destino debe estar configurada en Capa Lógica.

Agregaremos una columna para generar un PK utilizando la función newuuid() y añadiremos las columnas de Empresa y Producto de nuestro objeto webhook con los objetivos apropiados:

orderxpcrud.png

xpcolumns.png

Nota

No necesitamos agregar el OrderNumber porque este se genera como parte del evento de inserción de la tabla de pedidos.

Paso 5: Crear una regla de negocio XP CRUD

Crea una regla de negocio XP CRUD que actualice y escriba una respuesta con el OrderNumber del nuevo pedido.

  1. Crea una nueva regla XP CRUD registrada en la fuente de datos del Webhook. Por ejemplo, PostOrder (Actualizar Respuesta).
  2. Establece la acción en Actualizar.
  3. Fuente de Datos a la fuente de datos de tu aplicación.
  4. Fuente de Datos de Destino a la fuente de datos de tu Webhook.
  5. Establece la Capa de Destino en Capa Lógica.
  6. Establece el Destino en tu Objeto Webhook. Por ejemplo, Webhook de Pedido.
  7. Agrega la tabla de pedidos de la fuente de datos de la aplicación.
  8. Agrega la columna OrderNumber apuntando a la columna de Respuesta.

  9. Agrega una cláusula Where que filtre 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 necesitamos convertir el OrderID a una cadena para que esto funcione.

Paso 6: Agregar las reglas de negocio CRUD como acciones

Agrega las dos Reglas de Negocio CRUD creadas al Evento de Inserción de la Capa de Lógica de la Regla de Negocio del Webhook.

insertevent.png

Paso 7: Exponer el webhook al mundo

Crea un Endpoint para tu Aplicación. Esto puede que ya se haya hecho para tu aplicación.

  1. Navega a App Builder IDE > REST APIs (Bajo Conectar) > Webhooks
  2. Haz clic en el botón Administrar Endpoints
  3. Selecciona la aplicación para la que deseas ingresar el valor del endpoint. Por ejemplo: WebhookDocumentation.
  4. Haz clic en el icono de lápiz de edición para la aplicación que estás configurando.
  5. Ingresa el valor del Endpoint en el campo de Endpoint. Por ejemplo WebhookDoc.
  6. Haz clic en continuar para guardar.
  7. Para configurar el Objeto Webhook, desde el Panel de Webhooks haz clic en +Webhook
  8. Selecciona tu Objeto Webhook. Se seleccionará automáticamente un Nombre de Endpoint. Esta será la parte del webhook de la URL del Webhook.

  9. Haz clic en Guardar

    exposewebhook.png

  10. (Opcional, desde App Builder 4.51.) Establece la opción de compatibilidad de recursos:

    1. Haz clic en el icono de abrir registro. Se abre el popup de Webhook.
    2. Abre el menú de Compatibilidad, luego selecciona una de las siguientes opciones:
    3. Versión 1: Usa el comportamiento REST original—los eventos de Inserción no son precedidos por eventos de Nuevo. (Predeterminado para endpoints creados con App Builder 4.50 y anteriores.)
    4. Versión 2: Usa un comportamiento REST mejorado—los eventos de Nuevo y cualquier regla predeterminada se invocan antes de los eventos de Inserción. (Predeterminado para endpoints creados con App Builder 4.51 y posteriores.)

Paso 8: Crear una clave API para que un usuario acceda a este webhook

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

  1. Navega a IDE, Proveedores de Seguridad
  2. Bajo Autenticación de Usuario, crea un registro de tipo Autenticación Básica HTTP si no existe uno. Si ya existe, puedes omitir este paso
  3. Navega a IDE, Gestión de Usuarios
  4. Selecciona el Usuario que necesita una Clave
  5. Bajo Autenticación, haz clic en Claves
  6. Haz clic en Crear
  7. Para Proveedor, selecciona el proveedor de seguridad de tipo Autenticación Básica HTTP de los pasos 1 y 2
  8. Haz clic en Guardar
  9. Anota el Identificador y la Clave generados, ya que esta información no estará disponible nuevamente

Paso 9: Probar

Puedes probar este Webhook usando Postman o Insomnia. Envía una llamada API POST con el Cuerpo similar al Muestra de Cuerpo utilizada para crear los parámetros en el Paso 1. Utilizarás autenticación básica con el identificador como el Nombre de Usuario y la Clave como la contraseña del paso anterior.

Para probar, utiliza el enlace: https://<url>/webhook/v1/<application-endpoint>/<endpoint>

En el escenario donde no se requiere autenticación, en lugar de configurar un x-api-key en el encabezado, puedes ajustar 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 paso9}} (para ser utilizado 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, utiliza el método de Clave API en su lugar.

  2. https://{{url del paso9}}?apiKey={{clave del usuario del Paso 8.9}} (para ser utilizado si el proveedor es Clave API y las Propiedades incluyen HttpHeaderName 'X-API-Key')