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 usa webhooks para activar acciones específicas en respuesta a correos electrónicos, mensajes de texto o llamadas a la 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:

• Paso 1: Agregar un servidor de datos de webhook
• Paso 2: Agregar el webhook a tu aplicación
• Paso 3: Crear una regla de negocio de webhook
• Paso 4: Crear una regla de negocio XP CRUD
• Paso 5: Exponer el webhook
• Paso 6: Crear una clave de API para un usuario
• Paso 7: Probar el 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 de 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 > Data Servers.

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

   

   1. Establece los valores para lo siguiente:

      • Server Name: Ingresa un nombre.

      • Type: Selecciona Webhook API. Esto muestra más opciones.

      • Request Content Type: Selecciona JSON.

      • Response Content Type: Selecciona JSON.

   2. Haz clic en Save.

   3. Cierra el diálogo.

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

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

2. Haz clic en el icono Open record:

   

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

   

4. Se abre la página Web Service. En el panel Endpoints, haz clic en + Endpoint:

   

   Establece los valores para los siguientes parámetros:

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

   • Endpoint: Puedes dejar este campo vacío.

   • Method: 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 Endpoints, haz clic en Discover. Se abre el diálogo Endpoint:

   

   1. Establece los valores para lo siguiente:

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

      • End Point: Puedes dejar este campo vacío.

      • Method: Selecciona POST.

      • Request Body: Si el webhook acepta un cuerpo (por ejemplo, un POST que usa 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 Discover. 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 y el punto de conexión del webhook definidos, vincula ese servidor a tu aplicación como 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 Webhook REST que configuraste en Paso 1 en la lista.

6. Haz clic en el botón Vincular.

7. Haz clic en Listo.

Paso 3: Crea 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:

   

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

4. Configura tu nueva regla de la siguiente manera:

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

   • Propósito: Selecciona Webhook. Esto hace que aparezcan 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: Crea una regla de negocio XP CRUD

La regla de webhook únicamente 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 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:

   

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

4. En el panel Acciones, haz clic en + Regla y registrar. Se abre una nueva instancia del Constructor 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 lógica.

   • Destino: Selecciona la regla de negocio que creaste en 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 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: Expone el webhook

Finalmente, expone la regla de webhook a través de la API REST de App Builder, para que sistemas externos puedan llamarla mediante 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:

   

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

5. Introduce 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 de API, HTTP o Servidor de autorización que deseas permitir para autenticar las solicitudes de Webhook de tu aplicación. Consulta Configura un punto de conexión para los pasos exactos.

   Nota

   Esta opción no está disponible en una aplicación sellada. Para una aplicación sellada, haz clic en el icono en su columna Servicio web en Administrar aplicaciones, que abre este mismo diálogo Proveedores de autenticación desde fuera de la aplicación.

7. Cierra el diálogo. En el panel Services, haz clic en el icono en el tile de tu aplicación. Se abre la página Webhook API, mostrando los paneles Service y Webhooks.

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

   

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

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

   

   Configúralo de la siguiente forma:

   • 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: Introduce el segmento de ruta donde se accede al webhook.

   • Compatibility: Deja la opción predeterminada. Consulta Compatibility para las opciones disponibles, que también se 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 el payload a medida que pasa por el webhook.

Paso 6: Crear una clave de API para un usuario

Finalmente, genera una clave de API para que un usuario específico pueda autenticar las 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:

   

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 forma:

   • Provider: Selecciona tu proveedor de seguridad de clave de API (consulta Paso 1: Configurar un proveedor de seguridad de clave de API si aún no has configurado uno).

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

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

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

Paso 7: Probar el webhook

Debes probar tu nuevo webhook (usando, por ejemplo, Postman, Insomnia o herramientas similares). Envía una llamada de API POST con un body similar al body de ejemplo utilizado para crear los parámetros en el 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 las pruebas, usa 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 header, 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 usar si el proveedor es HTTP basic auth sin parámetros)

   Precaución

   El método HTTP basic descrito anteriormente requiere que el header Authorization se incluya en el payload recibido. Para evitar esto, usa el método API Key en su lugar.

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

Solución de problemas

Para consultar una causa común de fallos en la autenticación del webhook, ve a Webhook: La autenticación HTTP Básica requiere el encabezado de Autorización en la carga útil en la guía de solución de problemas de App Builder.