Saltar al contenido

Webhooks en Jitterbit App Builder

Descripción general

Un webhook es una notificación automatizada que se envía entre aplicaciones cuando ocurre un evento específico. App Builder utiliza webhooks para activar acciones específicas en respuesta a correos electrónicos, mensajes de texto o llamadas API.

Por ejemplo, una aplicación podría enviar un correo electrónico a un usuario para aprobar o rechazar una transferencia. Si el usuario responde "aprobar", un webhook activa el proceso de aprobación; si responde "rechazar", activa el rechazo. Esto permite a los usuarios completar tareas directamente desde su bandeja de entrada o aplicación de mensajería sin tener que volver a iniciar sesión en la aplicación principal.

Esta página te enseña los pasos para crear y configurar un webhook:

Esta página también contiene una sección de Solución de problemas que aborda un error común de webhook y cómo resolverlo.

Crear un webhook

Sigue estos pasos para configurar y exponer un webhook de extremo a extremo:

Paso 1: Agregar un servidor de datos webhook

Un webhook necesita su propio servidor de datos, de tipo Webhook API, para recibir llamadas HTTP entrantes. Sigue estos pasos para crear uno:

  1. Navega al IDE.

  2. Selecciona IDE > Servidores de datos.

  3. Haz clic en + Servidor. Se abre el diálogo Servidor:

    diálogo de servidor

    1. Establece valores para lo siguiente:

      • Nombre del servidor: Ingresa un nombre.

      • Tipo: Selecciona Webhook API. Esto hace que se muestren más opciones.

      • Tipo de contenido de solicitud: Selecciona JSON.

      • Tipo de contenido de respuesta: Selecciona JSON.

    2. Haz clic en Guardar.

    3. Cierra el diálogo.

Con el servidor creado, define el punto de conexión específico al que llamará el webhook:

  1. En la lista de servidores, busca el servidor que acabas de crear y selecciónalo. Al hacerlo, se enumera el nuevo servidor en el otro panel de la pantalla.

  2. Haz clic en el icono Abrir registro:

    abrir registro

  3. Se abre el diálogo Webhook API. En la sección REST API, haz clic en Puntos de conexión:

    diálogo de webhook API

  4. Se abre la página Servicio web. En el panel Puntos de conexión, haz clic en + Punto de conexión:

    página de servicio web

    Establece valores para los siguientes parámetros:

    • Nombre: Elige un nombre para tu punto de conexión.

    • Punto de conexión: Puedes dejar este campo vacío.

    • Método: Selecciona POST.

  5. Haz clic en el icono de marca de verificación para guardar.

Finalmente, descubre los parámetros que proporcionará el cuerpo de la solicitud del webhook:

  1. En el panel Puntos de conexión, haz clic en Descubrir. Se abre el diálogo Punto de conexión:

    diálogo de punto de conexión

    1. Establece valores para lo siguiente:

      • Nombre: Este campo se completa automáticamente con el nombre que has elegido para el punto de conexión.

      • Punto de conexión: Puedes dejar este campo vacío.

      • Método: Selecciona POST.

      • Cuerpo de solicitud: Si el webhook acepta un cuerpo (por ejemplo, un POST usando JSON o tipo de contenido de solicitud XML), proporciona un cuerpo de solicitud de ejemplo. Por ejemplo:

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

    2. Haz clic en Descubrir. App Builder agrega automáticamente los parámetros del punto de conexión.

Paso 2: Agregar el webhook a tu aplicación

Con el servidor webhook y el punto de conexión definidos, vincula ese servidor en tu aplicación como una fuente de datos:

  1. Ve a App Workbench > Orígenes de datos.

  2. Haz clic en + Origen. Se abre un diálogo.

  3. Selecciona Vincular a un origen existente.

  4. Haz clic en Siguiente.

  5. Localiza y selecciona la API de Webhook REST que configuraste en el Paso 1 en la lista.

  6. Haz clic en el botón Vincular.

  7. Haz clic en Listo.

Paso 3: Crear una regla de negocio de webhook

A continuación, crea una regla de negocio que asigne los datos entrantes del webhook a un origen de datos utilizable:

  1. Ve a App Workbench > Orígenes de datos.

  2. En el panel Orígenes de datos de la aplicación, selecciona el origen de datos de webhook que acabas de crear:

    crear una regla

  3. En el panel Reglas, haz clic en + Regla. Se abre el Generador de reglas.

  4. Configura tu nueva regla de la siguiente manera:

    • Nombre: Ingresa un nombre descriptivo para la regla, por ejemplo, WebhookCreation.

    • Propósito: Selecciona Webhook. Al hacerlo, aparecen más opciones.

    • Origen de datos de origen: Selecciona el origen de datos de webhook del Paso 1.

    • Destino: Selecciona el punto de conexión de webhook del Paso 1.

  5. Haz clic en Crear. App Builder crea la regla y muestra su pantalla de edición.

  6. En el panel Tablas, haz clic en + Tablas. Se abre un diálogo.

  7. Selecciona el punto de conexión de webhook haciendo clic en su botón Agregar. Aparece en el panel Tablas.

  8. En el panel Tablas, selecciona todas las columnas del punto de conexión.

Paso 4: Crear una regla de negocio XP CRUD

La regla de webhook por sí sola solo define la forma de los datos entrantes. Adjunta una regla XP CRUD a su evento Insert para que los datos estén disponibles para otras reglas y tablas en tu aplicación:

  1. En la pantalla de edición de la regla de negocio que creaste en el Paso 3, haz clic en Eventos en el panel Regla. Se abre el diálogo Todos los eventos.

  2. Haz doble clic en la fila con el evento Insert. Se abre la ventana Insert:

    ventana insert

  3. En el panel Información del evento, selecciona Actualización de fila en el menú Alcance de actualización.

  4. En el panel Acciones, haz clic en + Regla y registrar. Se abre una nueva instancia del Generador de reglas. Configúralo de la siguiente manera:

    • Nombre: Dale un nombre descriptivo, por ejemplo, WebhookCreation_XP_CRUD.

    • Propósito: Selecciona XP CRUD.

    • Acción: Selecciona Insert.

    • Capa de destino: Selecciona Capa de lógica.

    • Destino: Selecciona la regla de negocio que creaste en el Paso 3.

  5. Haz clic en Crear. Se crea la nueva regla de negocio y aparece su pantalla de edición.

  6. En el panel Tablas, haz clic en + Tablas.

  7. Selecciona el punto de conexión que creaste en el Paso 1 haciendo clic en su botón Agregar. Se mostrará en el panel Tablas.

  8. Selecciona todas sus columnas.

  9. Haz clic en Validar.

Paso 5: Exponer el webhook

Finalmente, expón la regla de webhook a través de la API REST de App Builder, para que los sistemas externos puedan llamarla por HTTP:

  1. Selecciona IDE > API REST.

  2. Ve a la pestaña Webhooks.

  3. En el panel Servicios, haz clic en el botón Administrar puntos de conexión para abrir el diálogo Aplicaciones:

    Diálogo Aplicaciones

  4. Localiza tu aplicación y haz clic en su icono de lápiz.

  5. Ingresa un nombre para tu punto de conexión y luego haz clic en Continuar.

  6. (Desde App Builder 4.67.) Haz clic en el icono Autenticación de la aplicación. Se abre el diálogo Proveedores de autenticación. Agrega los proveedores de clave API, HTTP o servidor de autorización que deseas permitir para autenticar las solicitudes de Webhook de esta aplicación. Consulta Configurar un punto de conexión para conocer los pasos exactos.

  7. Cierra el diálogo. En el panel Servicios, haz clic en el icono de comilla angular en el mosaico de tu aplicación. Se abre la página API de Webhook, que muestra los paneles Servicio y Webhooks.

  8. (Desde App Builder 4.67.) En el panel Service, haz clic en More > Configure Authentication:

    More menu, Configure Authentication button

    Se abre el mismo diálogo Authentication Providers del paso 6. Agrega y guarda proveedores de la misma manera que se describe allí.

  9. En el panel Webhooks, haz clic en + Webhook. Se abre el diálogo Webhook:

    Webhook dialog

    Configúralo de la siguiente manera:

    • Webhook: Selecciona la regla de webhook que has creado. Una vez que se guarda el diálogo, el icono junto a este campo se vuelve clickeable y te lleva a la página Rule Builder de la regla en App Workbench.

    • Endpoint: Ingresa el segmento de ruta donde se accede al webhook.

    • Compatibility: Deja la opción predeterminada. Consulta Compatibility para ver las opciones disponibles, que también aplican aquí.

  10. Haz clic en Save.

  11. (Opcional.) Haz clic en el icono de detalles del webhook para ver el diálogo Webhook, donde puedes configurar plugins de solicitud/respuesta que transformen la carga útil mientras pasa por el webhook.

Paso 6: Crear una clave API para un usuario

Finalmente, genera una clave API para que un usuario específico pueda autenticar llamadas a este webhook:

  1. Selecciona IDE > User Management.

  2. En el panel Users, selecciona un usuario que tenga privilegios de administrador y haz doble clic en su fila. Se abre el diálogo User:

    user dialog

  3. Haz clic en More > Keys. Se abre el diálogo Keys.

  4. Haz clic en Create. Se abre el diálogo Generate Key.

  5. Configura la nueva clave de la siguiente manera:

    • Provider: Selecciona tu proveedor de seguridad de clave API (consulta Set up a security provider API key si aún no has configurado uno).

    • Description: (Opcional) Proporciona una breve descripción.

    • Expires In: (Opcional) Ingresa un tiempo de expiración personalizado.

  6. Haz clic en Save para crear la clave API.

Importante

Anota la información ya que no se puede mostrar nuevamente.

user dialog

Paso 7: Probar el webhook

Debes probar tu nuevo webhook (usando, por ejemplo, Postman, Insomnia o herramientas similares). Envía una llamada API POST con un cuerpo similar al ejemplo de cuerpo utilizado para crear los parámetros en Paso 1. Debes usar autenticación básica con el identificador y la clave del Paso 6 como nombre de usuario y contraseña.

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

Cuando no se requiere autenticación, en lugar de configurar una x-api-key en el encabezado, puedes ajustar la URL a una de las siguientes opciones:

  1. https://{{user's identifier from Step 6}}:{{user's key from Step 6}}@{{url from Step 7}} (para usarse si el proveedor es HTTP basic auth sin parámetros)

    Precaución

    El método HTTP basic descrito anteriormente requiere que el encabezado Authorization se incluya en la carga útil recibida. Para evitar esto, utiliza el método de clave API en su lugar.

  2. https://{{url from step7}}?apiKey={{user's key from Step 6}} (para usarse si el proveedor es API Key y las Properties incluyen HttpHeaderName 'X-API-Key')

Solución de problemas

Para una causa común de fallos de autenticación de webhook, consulta Webhook: HTTP Basic Auth requires the Authorization header in the payload en la Guía de solución de problemas de App Builder.