Saltar al contenido

¡Transforma tus conexiones en dinero para el final del año con nuestro nuevo Programa de Indicación de Clientes! Descubre más

✕

Esta documentación es para la versión 4 y posteriores de App Builder, el nuevo nombre de Vinyl. Accede a la documentación de Vinyl aquí.

✕

Webhooks en Jitterbit App Builder

Descripción general

App Builder permite invocar un evento en respuesta a un correo, un mensaje de texto o una llamada a la API a un extremo de App Builder mediante webhooks. Los webhooks son devoluciones de llamada HTTP definidas por el usuario y suelen activarse 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 una aplicación de App Builder envía un correo a un usuario solicitá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", App Builder invoca un evento; "rechazar", se invoca otro. 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 una aplicación de App Builder para la gestión de pedidos. El usuario desea crear un nuevo pedido mediante una llamada a la API y recibir el número de pedido en la respuesta de la API. El objetivo del webhook es generar un nuevo registro de pedido, calcular el número de pedido y devolverlo 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 los 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 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:

      orderdataserver.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.

    • Selecciona el Método HTTP que usa tu webhook. Normalmente será un POST para actualizar la información de 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 (p. ej., un POST con contenido de tipo solicitud JSON o XML), proporcione un Cuerpo de solicitud de ejemplo. En nuestro ejemplo, nuestro JSON es:

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

      (Generaremos el ID y el número de pedido 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 del 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 valor de prueba, sin tipo seleccionado para cookie/encabezado/consulta y con la dirección como 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. Revise el resumen de lo que realizará App Builder y haga clic en Listo

Paso 3: Crear una regla de negocio 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. 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 de XP

Cree una regla de negocio CRUD de XP que inserte el valor recibido del webhook en una tabla de la fuente de datos de su aplicación. Esta debe registrarse en la fuente de datos del webhook, como el objeto webhook que acabamos de crear. Notas:

  • La tabla de pedidos debe permitir la lectura y escritura públicas, lo cual 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 estar configurada como capa lógica.

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

orderxpcrud.png

xpcolumns.png

Nota

No es necesario agregar el número de pedido, ya que este se genera como parte del evento de inserción de la tabla de pedidos.

Paso 5: Crear una regla de negocio CRUD de XP

Cree una regla de negocio 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 el objeto de su webhook. Por ejemplo, Webhook de pedidos.
  7. Añada la tabla de pedidos desde la fuente de datos de la aplicación.
  8. Añada la columna de número de pedido que tenga como destino la columna de respuesta.

  9. Añada 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 necesitamos convertir el ID del pedido a 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 esté hecho.

  1. Vaya a App Builder IDE > REST APIs (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 icono 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 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 la asignaremos a un usuario para que acceda a este webhook. Esto puede hacerse 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

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

Para probar, 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, potencialmente 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 usar si el proveedor usa 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 evitarlo, utilice el método de clave API.

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