Webhooks

Un webhook es una URL especificada por el socio en la que la plataforma de RCS para empresas 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 verse así: https://[your company name].com/api/rbm-events. Una vez que configures tu webhook, podrás comenzar a recibir mensajes y eventos.

Webhooks del socio y webhooks del agente

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

  • El webhook del 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 del 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 del socio y un webhook del agente, el webhook del agente tiene prioridad en su agente específico, mientras que el webhook del 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 tu webhook del socio. Si quieres que los mensajes de un agente específico lleguen a un webhook diferente, establece un webhook del agente.

  1. Abre la Consola para desarrolladores de RCS para empresas y accede con tu Cuenta de Google de socio de RCS para empresas.
  2. Haz clic en tu agente.
  3. Haz clic en Integrations.

  4. En la sección Webhook, haz clic en Configurar.

    1. En Webhook endpoint, ingresa la URL del webhook que comience con "https://".
    2. En Client token, especifica tu clientToken valor. Lo necesitas para verificar que los mensajes que recibes provengan de Google.

  5. Configura tu webhook para que acepte solicitudes POST con una carga útil de JSON que incluya los parámetros clientToken y secret.

    {
  "clientToken":"YOURCLIENTTOKEN",
  "secret":"YOURSECRET"
}

    Para validar la solicitud, tu extremo debe devolver un código de estado HTTP 200 OK con el valor de cadena sin procesar del parámetro secret en el cuerpo de la respuesta.

    Configuración de webhook de muestra

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

      {
  "clientToken":"YOURCLIENTTOKEN",
  "secret":"YOURSECRET"
  }

    Tu webhook debe confirmar el valor clientToken y, si clientToken es correcto, devolver una respuesta 200 OK con YOURSECRET como cuerpo de la respuesta:

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

  // Example endpoint
  app.post("/rbm-webhook", (req, res) => {
    // Use the X-Goog-Webhook-Type header to route requests
    const webhookType = req.header('X-Goog-Webhook-Type');

    if (webhookType === 'verification') {
      const msg = req.body;
      if (msg.clientToken === myClientToken) {
          res.status(200).send(msg.secret);
          return;
      }
    }
    res.send(400);
    // Handle other webhook types
  });

  6. En la Consola para desarrolladores, haz clic en Verificar. Después de hacer clic en Verificar, Google envía una solicitud POST a tu webhook con los parámetros clientToken y secret dentro del cuerpo de la solicitud. Cuando RCS para empresas verifica tu webhook, se cierra el diálogo.

Identifica los tipos de solicitudes

Para identificar el tipo de solicitud de todas las solicitudes que llegan a tu webhook, usa el encabezado X-Goog-Webhook-Type.

El encabezado puede tener los siguientes valores:

  • verification: Se usa para el proceso inicial de verificación de extremos.
  • message_callback: Se usa para eventos relacionados con mensajes, como notificaciones de escritura o entrega, y mensajes entrantes de los usuarios.
  • agent_callback: Se usa para eventos administrativos específicos del agente, como cambios en el estado de lanzamiento del agente.

Verifica los mensajes entrantes

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

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

  1. Extrae el encabezado X-Goog-Signature del mensaje. Esta es una copia hash codificada en base64 de la carga útil del cuerpo del mensaje.
  2. Decodifica en base64 la carga útil de RCS para empresas en el elemento message.body de la solicitud.
  3. Con el token de cliente de tu webhook (que especificaste cuando configuraste tu webhook) 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 hash que creaste.
    • Si los hashes coinciden, confirmaste que Google envió el mensaje.

    • Si los hashes no coinciden, verifica tu proceso de hashing en un mensaje que se sepa que es correcto.

      Si tu proceso de hashing 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
    const headerHash = req.header('X-Goog-Signature');
    const userEventString = Buffer.from(requestBody.message.data, 'base64');
    const hmac = crypto.createHmac('sha512', myClientToken);
    const genHash = hmac.update(userEventString).digest('base64');

    if (headerHash === genHash) {
      const userEvent = JSON.parse(userEventString);
      const webhookType = req.header('X-Goog-Webhook-Type');

      // Route based on the header type
      if (webhookType === 'message_callback') {
        handleMessage(userEvent);
      } else if (webhookType === 'agent_callback') {
        handleAgentEvent(userEvent);
      }
    } else {
      console.log('Hash mismatch - ignoring message');
      res.sendStatus(401);
      return;
    }
  }

  res.sendStatus(200);

Control de mensajes

Devolver cualquier valor que no sea 200 OK desde un webhook se considera una falla en la entrega.

Los desarrolladores deben tener en cuenta que enviar 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 las fallas de nivel superior. Entre las cosas que se deben tener en cuenta, se incluyen las siguientes:

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

Los desarrolladores deben diseñar sus sistemas de modo que el procesamiento de eventos de RBM se realice 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 retorno del webhook:

Procesamiento síncrono de webhooks

Comportamiento en caso de falla en la entrega

Si tu webhook devuelve un estado que no sea 200 OK, la plataforma de RCS para empresas usa un mecanismo de espera y reintento para volver a entregar los datos. Esto significa que el sistema aumenta progresivamente la demora entre cada intento de entrega y, finalmente, alcanza una frecuencia máxima de un reintento cada 10 minutos para cada mensaje pendiente. El ciclo de reintento continúa durante siete días, después de los cuales el mensaje se borra de forma permanente.

Implicaciones de los webhooks a nivel de agente

RCS para empresas pone en cola los mensajes de un socio en una sola cola. Todos los agentes de una sola cuenta de socio comparten una sola cola. Por este motivo, una falla en un webhook puede bloquear toda la cola, lo que impide que los eventos del usuario para todos los agentes lleguen al socio.

Varios mensajes no confirmados pueden causar un aumento masivo en los eventos de reintento. Por ejemplo, si un agente no confirma 1,600 recibos de entrega y la frecuencia de reintento alcanza el límite de 10 minutos, puede generar aproximadamente 230,000 errores potenciales por día:

1,600 mensajes × 6 reintentos por hora × 24 horas por día = aproximadamente 230,000 errores por día

Este volumen de reintentos puede bloquear la cola compartida de Pub/Sub y causar demoras significativas en la recepción de eventos del usuario para todas las campañas de un socio.

Prácticas recomendadas

Para garantizar la confiabilidad de tu tráfico de producción y evitar bloqueadores de colas, sigue estas prácticas recomendadas:

  • Devuelve 200 OK de inmediato: El webhook debe recibir el mensaje, almacenarlo en una cola local y devolver una respuesta 200 OK en menos de cinco segundos.
  • Desvincula el procesamiento: Usa trabajadores en segundo plano independientes para procesar la lógica de mensajes desde la cola local.
  • Supervisa los agentes de prueba: Trata a los agentes de desarrollo como agentes de producción, ya que también pueden bloquear la cola compartida del socio si fallan.
  • Cuentas dedicadas para pruebas: Es preferible usar una cuenta de desarrollador para los agentes de producción y una cuenta de desarrollador dedicada para los agentes de prueba.
  • Verifica el tráfico de Google: Usa DNS inverso o el encabezado X-Goog-Signature en lugar de la lista de entidades permitidas de IP fijas, ya que Google usa IPs de anycast dinámicas. Para obtener más información sobre la verificación manual y la identificación de rangos de IP de Google, consulta la documentación Verifica las solicitudes de Google y, específicamente, los archivos JSON para los recuperadores activados por el usuario y los recuperadores activados por el usuario de Google.

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