Webhooks by Kissflow

Conceptos básicos de webhook

Un webhook (también conocido como callback web) es un método para que cualquier software proporcione información en tiempo real a otras aplicaciones. Los webhooks te permiten crear o configurar integraciones que se suscriben a determinados eventos en tu aplicación. Cuando se activa uno de esos eventos, enviaremos una carga HTTP POST a la URL configurada del webhook. Se diferencia de las API habituales en que no necesitas consultar los datos con tanta frecuencia para obtenerlos en tiempo real.

Trabajar con Webhooks by Kissflow

Kissflow puede integrarse con aplicaciones de terceros mediante webhooks o callbacks HTTP definidos por el usuario. Para que las aplicaciones de terceros consuman el webhook de Kissflow, proporcionamos una URL a la que se enviarán las solicitudes. Busca la página de configuración de webhooks de la aplicación que quieres conectar a Kissflow.

En la configuración de webhook de tu aplicación, normalmente elegirás añadir una nueva conexión de webhook. Pega la URL del webhook que copiaste del conector Webhooks de Kissflow, selecciona cualquiera de las opciones que ofrece la aplicación —incluidos los datos que quieres recibir mediante el webhook— y guarda los cambios.

Por ejemplo, puedes configurar una integración para que cada vez que se cree una nueva solicitud de compra en tu software ERP, puedas iniciar un proceso de aprobación en Kissflow (acción). También puedes configurar una integración para que cualquier nuevo suscriptor de correo electrónico en MailChimp se añada automáticamente a tu hoja de Google. Tus posibilidades solo están limitadas por tu imaginación.

Desencadenadores en el conector de webhook

Configurar tu webhook

1. En tu cuenta de Kissflow, haz clic en el botón Crear del panel de navegación izquierdo y selecciona Integración en la lista. Introduce un nombre y una descripción únicos para tu integración y haz clic en Crear.

2. En el editor, selecciona el desencadenador Webhooks by Kissflow. También puedes usar la búsqueda para encontrarlo directamente.

3. Haz clic en el menú desplegable Desencadenador, selecciona Capturar un webhook (POST) y haz clic en Siguiente.

4. Capturar un webhook funciona proporcionándote una URL única a la que puedes enviar solicitudes POST. Copia la URL y pégala en la configuración principal o en la página de opciones de tu aplicación. Si no la encuentras, consulta la documentación de ayuda y soporte de tu aplicación. Haz clic en Siguiente.

5. La aplicación conectada a la URL de tu webhook le enviará datos cada vez que se añada algo nuevo. Para probar un desencadenador de webhook, primero debes añadir algo nuevo a tu aplicación. Por ejemplo, si te estás conectando a Trello, puedes añadir una nueva tarjeta a tu tablero de Trello. El conector empezará a supervisar la URL y obtendrá cualquier carga de la aplicación.

6. Si se encuentran los datos enviados a la URL del webhook, el paso indicará que se completó correctamente y mostrará los datos recibidos.

7. Los datos recibidos por el conector de webhook pueden ser utilizados por otras aplicaciones para realizar acciones específicas.

Personalizar la respuesta

De forma predeterminada, un desencadenador de webhook devuelve una respuesta 200 OK al sistema que lo llama. Cuando quien llama necesita algo más que una confirmación, como un identificador de referencia o un valor de la solicitud que envió, define tu propia respuesta dentro del desencadenador. Tu personalización abarca las cabeceras, el tipo de contenido y el cuerpo, y el paso no tiene una opción de código de estado.

Kissflow envía la respuesta en cuanto recibe la solicitud, antes de que se ejecuten las acciones de la integración. Una respuesta confirma que la solicitud llegó, y no contiene ningún resultado de un paso posterior.

Para personalizar la respuesta,

1. Abre la integración y selecciona el desencadenador, Recibir un webhook (POST).
2. Selecciona Respuesta.
3. Activa Personalizar respuesta.

El paso pasa a tener dos secciones:

Añadir una solicitud de muestra

Copia una solicitud de la aplicación que llama al webhook, o de la carga capturada durante la prueba del desencadenador.

1. Pega las cabeceras de la solicitud en Cabeceras de muestra:

Cabeceras de muestra

{
  "Authorization": "Bearer abc123",
  "X-Caller-Ref": "a1b2c3"
}

2. Pega el cuerpo de la solicitud en Cuerpo de muestra:

Cuerpo de muestra

{
  "order_id": "8471",
  "status": "approved",
  "customer": {
    "name": "Dana Whitfield",
    "email": "dana@example.com"
  }
}

Ambos valores aparecen en Solicitud de webhook, agrupados como cuerpo y cabeceras. Los valores anidados están disponibles a través de su ruta, como customer.name.

Insertar un valor de la solicitud

Tanto una cabecera de respuesta como un campo del cuerpo admiten texto estático, un valor de la solicitud entrante o una combinación de ambos. Los valores de la solicitud se construyen en el generador de fórmulas.

1. Haz clic en fx junto al valor que estás construyendo.
2. En Campos de integración, abre Solicitud de webhook y selecciona el valor que quieras. Kissflow inserta su ruta, como context.webhookRequest.body.order_id.
3. Para unir texto y valores de la solicitud, usa concatenate, que aparece en Texto dentro de Funciones.
4. Haz clic en Evaluar para ver el resultado con tu muestra y luego guarda.

Un valor combinado

concatenate("Order ", context.webhookRequest.body.order_id, " received for ", context.webhookRequest.body.customer.name)

Con la muestra anterior, esto devuelve Order 8471 received for Dana Whitfield. Los espacios van dentro del texto entre comillas, porque concatenate une sus valores sin nada entre ellos.

Añadir cabeceras de respuesta

En Respuesta, haz clic en Añadir cabecera e introduce una Clave y un Valor para cada cabecera que reciba quien llama.

Una cabecera entrante se resuelve con las mayúsculas y minúsculas con las que la envíe quien llama, así que un valor leído de X-Caller-Ref se sigue resolviendo cuando la solicitud lleva x-caller-ref.

Seleccionar un tipo de contenido

Selecciona una de las dos opciones en Content-Type:

Construir el cuerpo de la respuesta

Cada campo de un cuerpo JSON forma una clave en la respuesta. Asigna a cada campo una Clave y un Valor.

Quien llama recibe entonces:

Cuerpo de la respuesta

{
  "order_id": "8471",
  "message": "Order 8471 received for Dana Whitfield"
}

Un cuerpo de texto contiene los mismos valores en línea, y quien llama recibe:

Order 8471 received for Dana Whitfield

Haz clic en Siguiente para guardar la respuesta, completar los pasos restantes y activar la integración.

Cuando una solicitud no se puede responder

Insertar un valor de la solicitud en tu respuesta hace que ese campo sea obligatorio. Kissflow construye la respuesta antes de ejecutar la integración, así que una solicitud que no lleve todos los campos insertados no se puede responder, y se rechaza en lugar de responderse parcialmente.

En cada caso la integración no se ejecuta y no se registra nada en el historial de ejecuciones, así que quien llama puede corregir la solicitud y enviarla de nuevo.

Inserta un valor de la solicitud cuando quien llama siempre lo envíe, o cuando una solicitud sin él deba rechazarse. Para responder a todas las solicitudes lleven lo que lleven, construye la respuesta con texto estático.

Activar el conector de webhook

Después de configurar el conector, activa el botón de alternancia en la esquina superior derecha del editor para activar la integración.

Para asegurarte de que tus integraciones estén configuradas y probadas correctamente, consulta nuestra guía de prácticas recomendadas para obtener consejos sobre cómo crear soluciones sólidas y fáciles de mantener.