Webhooks

Un webhook es una URL especificada por el socio en la que la plataforma de RBM publica mensajes y eventos. Esta URL actúa como un extremo que recibe solicitudes HTTPS POST que contienen datos sobre los eventos. Esto significa que los datos se envían a tu aplicación de forma segura a través de HTTPS.

Una URL de webhook podría tener el siguiente aspecto: https://[your company name].com/api/rbm-events. Una vez que configures tu webhook, podrás comenzar a recibir mensajes y eventos.

Webhooks de socios y webhooks de agentes

Puedes configurar tu webhook a nivel del socio o del agente.

  • Tu webhook de socio se aplica a todos los agentes que mantienes. Si tus agentes tienen un comportamiento similar o si solo tienes uno, usa el webhook del socio.
  • Los webhooks de agente se aplican a agentes individuales. Si operas varios agentes con un comportamiento distinto, puedes establecer un webhook diferente para cada agente.

Si configuraste un webhook de socio y un webhook de agente, el webhook de agente tiene prioridad en su agente específico, mientras que el webhook de socio se aplica a los agentes que no tienen su propio webhook.

Configura un webhook del agente

Recibirás los mensajes que se envíen a tu agente en el webhook de socio. Si quieres que los mensajes de un agente específico lleguen a un webhook diferente, configura un webhook del agente.

  1. Abre Business Communications Developer Console y accede con tu Cuenta de Google de socio de RBM.
  2. Haz clic en tu agente.
  3. Haz clic en Integrations.
  4. En Webhook, haz clic en Configurar.
  5. En URL del extremo del webhook, ingresa la URL del webhook que comienza con "https://".
  6. Anota tu valor de clientToken. Lo necesitas para verificar que los mensajes que recibes provienen de Google.

  7. Configura tu webhook para que acepte una solicitud POST con el parámetro clientToken especificado y envíe una respuesta 200 OK con el valor de texto sin formato del parámetro secret como cuerpo de la respuesta.

    Por ejemplo, si tu webhook recibe una solicitud POST con el siguiente contenido del cuerpo

    {
  "clientToken":"SJENCPGJESMGUFPY",
  "secret":"1234567890"
}

    entonces tu webhook debería confirmar el valor de clientToken y, si clientToken es correcto, devolver una respuesta 200 OK con 1234567890 como cuerpo de la respuesta:

    // clientToken from Configure
const myClientToken = "SJENCPGJESMGUFPY";

// Example endpoint
app.post("/rbm-webhook", (req, res) => {
  const msg = req.body;
  if (msg.clientToken === myClientToken) {
      res.status(200).send(msg.secret);
      return;
  }
  res.send(400);
});

  8. En la consola de Google Developers, haz clic en Verificar. Cuando RBM verifique tu webhook, se cerrará el diálogo.

Cómo verificar los mensajes entrantes

Dado que los webhooks pueden recibir mensajes de cualquier remitente, debes verificar que Google haya enviado los mensajes entrantes antes de procesar el contenido de los mensajes.

Para verificar que Google envió un mensaje que recibiste, sigue estos pasos:

  1. Extrae el encabezado X-Goog-Signature del mensaje. Es una copia con hash y codificada en base64 de la carga útil del cuerpo del mensaje.
  2. Decodifica en Base64 la carga útil de RBM en el elemento message.body de la solicitud.
  3. Con el token de cliente de tu webhook (que especificaste cuando lo configuraste) como clave, crea un HMAC SHA512 de los bytes de la carga útil del mensaje decodificado en base64 y codifica el resultado en base64.
  4. Compara el hash X-Goog-Signature con el que creaste.
    • Si los hashes coinciden, confirmaste que Google envió el mensaje.

    • Si los hashes no coinciden, revisa el proceso de codificación hash en un mensaje que se sepa que funciona correctamente.

      Si tu proceso de hash funciona correctamente y recibes un mensaje que crees que se te envió de forma fraudulenta, comunícate con nosotros.

Node.js

  if ((requestBody.hasOwnProperty('message')) && (requestBody.message.hasOwnProperty('data'))) {
    // Validate the received hash to ensure the message came from Google RBM
    let userEventString = Buffer.from(requestBody.message.data, 'base64');
    let hmac = crypto.createHmac('sha512', CLIENT_TOKEN);
    let data = hmac.update(userEventString);
    let genHash = data.digest('base64');
    let headerHash = req.header('X-Goog-Signature');

    if (headerHash === genHash) {
      let userEvent = JSON.parse(userEventString);

      console.log('userEventString: ' + userEventString);
      handleMessage(userEvent);
    } else {
      console.log('hash mismatch - ignoring message');
    }
  }

  res.sendStatus(200);

Control de mensajes

Si se devuelve algo que no sea 200 OK desde un webhook, se considera que la entrega falló.

Los desarrolladores deben tener en cuenta que el envío de mensajes a altas velocidades generará notificaciones de webhook a altas velocidades y deben diseñar su código para controlar las notificaciones a la velocidad esperada. Es importante que los desarrolladores tengan en cuenta las situaciones que pueden causar respuestas de error, incluidas las respuestas 500 de su contenedor web, los tiempos de espera o los errores de nivel superior. Estos son algunos aspectos que debes tener en cuenta:

  • Verifica que tus protecciones contra DDoS estén configuradas para controlar la tasa esperada de notificaciones de webhook.
  • Confirma que los recursos, como los grupos de conexiones de bases de datos, no se agoten y no produzcan tiempos de espera agotados ni respuestas 500.

Los desarrolladores deben diseñar sus sistemas de modo que el procesamiento de los eventos de RBM se produzca de forma asíncrona y no impida que el webhook devuelva 200 OK.

Procesamiento asíncrono de webhook

Es importante no procesar el evento de RBM dentro del webhook. Cualquier error o demora durante el procesamiento puede afectar el código de devolución del webhook:

Procesamiento síncrono de webhooks

Comportamiento en caso de error de entrega

RBM usa un mecanismo de reintento y espera cuando recibe una respuesta que no es 200 OK de una llamada de webhook. El RBM aumentará el tiempo de espera entre los reintentos hasta un máximo de 600 segundos. Los reintentos continuarán durante 7 días, después de lo cual se descartará el mensaje.

Implicaciones de los webhooks a nivel del agente

RBM pone en cola los mensajes de un socio en una sola cola. Cuando un socio usa webhooks a nivel del agente, es importante tener en cuenta que la falla de un webhook afectará la entrega a otros webhooks. Los webhooks que pertenecen a otros agentes se llamarán durante el período de espera de un mensaje fallido. Sin embargo, a medida que los mensajes con errores se pongan en cola para reintentarse, las tasas de entrega generales disminuirán y otros agentes se verán afectados.

Es importante que los desarrolladores comprendan este modelo y programen en consecuencia, aceptando mensajes y poniéndolos en cola para su procesamiento en la medida de lo posible, para minimizar la oportunidad de devolver un error.

Próximos pasos

Una vez que configures tu webhook, tu agente podrá recibir mensajes de tus dispositivos de prueba. Envía un mensaje para validar tu configuración.

Siguiente
Dialogflow