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 desencadenar 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 desencadena el proceso de aprobación; si responden "rechazar", desencadena un rechazo. Esto permite que los usuarios completen 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. Sal del diálogo.

Con el servidor creado, define el endpoint específico al que llamará el webhook:

  1. En la lista de servidores, encuentra el servidor que acabas de crear y selecciónalo. Al hacerlo, se muestra 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 Endpoints:

    diálogo de webhook API

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

    página de servicio web

    Establece valores para los siguientes parámetros:

    • Nombre: Elige un nombre para tu endpoint.

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

    diálogo de endpoint

    1. Establece valores para lo siguiente:

      • Nombre: Este campo se completa automáticamente con el nombre que has elegido para el endpoint.

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

      • Método: Selecciona POST.

      • Cuerpo de la 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 endpoint.

Paso 2: Agregar el webhook a tu aplicación

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

  1. Ve a App Workbench > Fuentes de datos.

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

  3. Selecciona Vincular a una fuente 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 una fuente de datos utilizable:

  1. Ve a App Workbench > Fuentes de datos.

  2. En el panel Fuentes de datos de la aplicación, selecciona la fuente de datos de webhook que acabas de crear:

    crear una regla

  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: Ingresa un nombre descriptivo para la regla, por ejemplo, WebhookCreation.

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

    • Fuente de datos de origen: Selecciona la fuente de datos de webhook del Paso 1.

    • Destino: Selecciona el punto final del 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 final del webhook haciendo clic en su botón Agregar. Aparece en el panel Tablas.

  8. En el panel Tablas, selecciona todas las columnas del punto final.

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 Constructor de reglas. Configúralo de la siguiente manera:

    • Nombre: Asígnale 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 final 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, expone 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 finales 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 final y luego haz clic en Proceder.

  6. (A partir de 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 final para conocer 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 Aplicaciones en su lugar, 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 de chevron en la tarjeta 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:

    Menú More, botón Configure Authentication

    Se abre el mismo diálogo Authentication Providers del paso 6. Añade 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:

    Diálogo Webhook

    Configúralo de la siguiente manera:

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

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

    • Compatibility: Mantén la opción predeterminada. Consulta Compatibility para ver 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 la carga útil mientras pasa por el webhook.

Paso 6: Crear una clave de API para un usuario

Por último, genera una clave de 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:

    diálogo de usuario

  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 API Key (consulta Configurar un proveedor de seguridad de clave 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.

Importante

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

diálogo de usuario

Paso 7: Prueba el webhook

Debes probar tu nuevo webhook (utilizando, por ejemplo, Postman, Insomnia u herramientas similares). Envía una llamada API POST con un cuerpo similar al ejemplo de cuerpo 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, utiliza el siguiente enlace: https://<url>/webhook/v1/<application-endpoint>/<endpoint>.

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

  1. https://{{identificador del usuario del Paso 6}}:{{clave del usuario del Paso 6}}@{{url del Paso 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 esté incluido en la carga útil recibida. Para omitir esto, utiliza el método API Key en su lugar.

  2. https://{{url del paso 7}}?apiKey={{clave del usuario del Paso 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 webhooks, consulta 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.