Cuando crea un webhook, especifica una URL y se suscribe a tipos de eventos. Cuando ocurre un evento al que su webhook está suscrito, Fluid enviará una solicitud HTTP con datos sobre el evento a la URL que especificó. Si su servidor está configurado para escuchar las entregas de webhooks en esa URL, puede realizar una acción cuando recibe una.

Este artículo describe cómo escribir código para que su servidor escuche y responda a las entregas de webhooks. Probará su código utilizando su computadora como servidor local.

Para manejar las entregas de webhooks, debe escribir código que realice lo siguiente:

• Inicializar su servidor para escuchar solicitudes a la URL de su webhook

• Leer los encabezados HTTP y el cuerpo de la solicitud

• Realizar la acción deseada en respuesta a la solicitud
  

Puede utilizar cualquier lenguaje de programación que pueda ejecutar en su servidor.

Los siguientes ejemplos imprimen un mensaje cuando se recibe una entrega de webhook. Sin embargo, puede modificar el código para realizar otra acción, como hacer una solicitud a la API de Fluid o enviar un mensaje de Slack.

Este ejemplo utiliza Node.js y la biblioteca Express para definir rutas y manejar solicitudes HTTP. Para obtener más información, consulte expressjs.com

Este ejemplo requiere que su computadora ejecute Node.js versión 12 o superior y npm versión 6.12.0 o superior. Para obtener más información, consulte nodejs.org

Para usar este ejemplo, debe instalar node.js y la biblioteca express en su proyecto de Node.js. Por ejemplo:

npm install nodejs

instalar express

npm install express

const express = require('express');
const bodyParser = require('body-parser');
const crypto = require('crypto');

const app = express();
const port = 3000;

// Middleware to parse JSON bodies as text,
// so we dont get issues like "prop":1.0 being changed to "prop":1
// as the payload is used for signature-256 validation
app.use(bodyParser.text({
   type: 'application/json'
}))

// Function to validate the X-Hub-Signature header
function validateSignature(req, res, next) {

    const sharedSecret = '#######'; // Replace with your shared secret
    const signature = req.headers['x-hub-signature-256'];
    const payload = req.body;

    if (!signature) {
    console.log(`X-Hub-Signature header missing`);
        return res.status(400).send('X-Hub-Signature-256 header missing');
    }

  const hmac = crypto.createHmac('sha256', sharedSecret);
  const calculatedSignature = hmac.update(payload).digest('hex');

     if (crypto.timingSafeEqual(Buffer.from(signature), Buffer.from('sha256=' + calculatedSignature))) {
      console.log(`X-Hub-Signature-256 is VALID`);
        next();
    } else {
    console.log(`X-Hub-Signature-256 is INVALID`);
        return res.status(403).send('Invalid X-Hub-Signature-256');
    }
}

  app.post('/', validateSignature, (req, res) => {

  const jsonData = JSON.parse(req.body);
  const prettifiedJson = JSON.stringify(jsonData, null, 2);

  console.log('Received VALID POST request with body:', prettifiedJson);

  res.json(prettifiedJson); // Echo back the request body
});

// Start the server
app.listen(port, () => {
    console.log(`Server is listening at http://localhost:${port}`);
});

Para probar su webhook, puede usar su computadora para actuar como servidor local. Si tiene problemas con estos pasos, consulte Solución de problemas de webhooks.

node FILE_NAME

Reemplace FILE_NAME con el nombre de su archivo, por ejemplo server.js. Debería ver una salida que dice Server is running on port 3000.

Para probar su webhook localmente, puede usar una URL de proxy de webhook para reenviar los webhooks desde Fluid a su computadora. Este artículo usa ngrok https://ngrok.com para proporcionar una URL de proxy de webhook y reenviar los webhooks.

1. Siga las instrucciones en https://ngrok.com/download para instalar la versión correcta de ngrok para su sistema operativo. El registro en ngrok es gratuito.

   Una vez que se haya registrado, inicie sesión en el panel y anote el token de autenticación https://dashboard.ngrok.com/get-started/your-authtoken, lo necesitará como parte de su instalación.

   También puede seguir su propia guía de introducción a los webhooks aquí https://ngrok.com/docs/integrations/hostedhooks/webhooks para obtener información adicional.

   Los siguientes detalles son para la instalación en Windows.
   

2. Abra una consola cmd de Windows y ejecute el siguiente comando.

   choco install ngrok

3. Autentique ngrok; puede encontrar su token aquí https://dashboard.ngrok.com/get-started/your-authtoken después de registrarse en ngrok.

   ngrok config add-authtoken <### Token ###>

4. Para recibir los webhooks reenviados desde ngrok, ejecute el siguiente comando en su terminal. Reemplace PORT con el puerto en el que está escuchando su servidor local.

   ngrok http PORT

5. Para recibir los webhooks reenviados desde ngrok, ejecute el siguiente comando en su terminal. Reemplace PORT con el puerto en el que está escuchando su servidor local.

   ngrok http PORT

   

6. Tome nota del valor de la URL de ngrok (resaltada en la captura de pantalla anterior); esta es la URL pública que utilizará para configurar los webhooks a Fluid Boards. Estos eventos que se envían a esta URL ahora se reenviarán a su servidor local que escucha en el puerto 3000.  En este ejemplo la URL es "https://a346-185-245-255-247.ngrok-free.app"
   

   Nota: Cada vez que ejecute ngrok http PORT recibirá una nueva URL pública; deberá actualizar la configuración del webhook de Fluid en consecuencia. Consulte Cómo configurar webhooks para la integración con Fluid Boards

Cree un webhook con la siguiente configuración. Para obtener más información, consulte Cómo configurar webhooks para la integración con Fluid Boards.

• Para la URL, use la URL que se muestra en el panel de ngrok http://localhost:4040 de antes, por ejemplo 
  

1. Active su webhook. Por ejemplo, si configuró su webhook de acción para suscribirse al evento de creación, cree una nueva acción. 

2. Navegue a el panel de ngrok en http://localhost:4040. En la pestaña de inspección, debería ver un evento que corresponde al evento que activó. Esto indica que Fluid envió correctamente una entrega de webhook a la URL que especificó en la configuración. También puede inspeccionar los detalles de los encabezados HTTP enviados por Fluid o repetir el mensaje nuevamente.

   

3. En la ventana de terminal donde ejecutó node FILE_NAME, debería ver el mensaje del evento correspondiente al evento que se envió.

4. En ambas ventanas de terminal, presione Ctrl+C para detener su servidor local y dejar de escuchar los webhooks reenviados.

Ahora que ha probado su código localmente, puede realizar cambios para usar su webhook en producción. Para obtener más información, consulte "Próximos pasos". Si tuvo problemas para probar su código, intente los pasos en Solución de problemas de webhooks.

Si no ve los resultados esperados descritos en los pasos de prueba, intente lo siguiente:

• Asegúrese de que su webhook esté usando su URL de proxy de webhook (la URL de ngrok que se encuentra en el panel  http://localhost:4040). Para obtener más información sobre la configuración de su webhook, consulte Cómo configurar webhooks para la integración con Fluid Boards.

• Asegúrese de que su webhook use el tipo de contenido JSON.

• Asegúrese de que tanto el cliente de ngrok como su servidor local estén en ejecución. Tendrá estos procesos ejecutándose en dos ventanas de terminal independientes.

• Asegúrese de que su servidor esté escuchando en el mismo puerto al que ngrok está reenviando los webhooks. Todos los ejemplos de este artículo usan el puerto 3000.

• Revise si hay mensajes de error en las ventanas de terminal donde está ejecutando el cliente de ngrok y su servidor local.

• Revise la URL de proxy de webhook en ngrok. Debería ver un evento que corresponde al evento que activó. Esto indica que Fluid envió correctamente una entrega de webhook a la URL de payload que especificó.
  
  

Este artículo demostró cómo escribir código para manejar las entregas de webhooks. También demostró cómo probar su código utilizando su computadora o codespace como servidor local y reenviando las entregas de webhooks desde Fluid a su servidor local mediante ngrok.com. Una vez que haya terminado de probar su código, es posible que desee modificar el código e implementarlo en un servidor.

Este artículo proporcionó ejemplos básicos que imprimen un mensaje cuando se recibe una entrega de webhook. Es posible que desee modificar el código para realizar alguna otra acción. Por ejemplo, podría modificar el código para:

• Enviar un mensaje en Slack

• Registrar eventos

• Actualizar una herramienta externa

En el código que maneja las entregas de webhooks, debe validar que la entrega proviene de Fluid  antes de seguir procesándola. Para obtener más información, consulte Validación de webhooks.

Este artículo demostró cómo usar su computadora o codespace como servidor mientras desarrolla su código. Una vez que el código esté listo para su uso en producción, debe implementarlo en un servidor dedicado.

Al hacerlo, es posible que deba actualizar su código para reflejar el host y el puerto en los que está escuchando su servidor.

Una vez que tenga un servidor configurado para recibir tráfico de webhooks de Fluid, actualice la URL en la configuración del webhook de su tablero de Fluid.  Es posible que deba actualizar la ruta que maneja su código para que coincida con la parte de ruta de la nueva URL. 

No debe usar ngrok.com para reenviar sus webhooks en producción.

Debe procurar seguir las prácticas recomendadas con sus webhooks. Para obtener más información, consulte Prácticas recomendadas para webhooks.

Solución de problemas de webhooks
Prácticas recomendadas para webhooks
Eventos y payloads de webhooks