Webhooks

Un webhook es una devolución de llamada HTTPS creada por un socio que especifica cómo debe responder tu agente a los mensajes y eventos. Una vez que configures el webhook, puedes comenzar a recibir mensajes y eventos.

Webhooks de socios y de agentes

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

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

Si configuraste un webhook de socio y un webhook de 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 de agente

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

  1. Abre Business Communications Developer Console y accede con la Cuenta de Google de tu 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 de tu webhook que comience con "https://".
  6. Anota el valor de clientToken. La necesitas para verificar que los mensajes que recibes provengan de Google.

  7. Configura tu webhook para que acepte una solicitud POST con el parámetro clientToken especificado y envía 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 de POST con el siguiente contenido del cuerpo

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

    entonces, tu webhook debe confirmar el valor clientToken y, si clientToken es correcto, mostrar una respuesta 200 OK con 1234567890 como el 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 Play Console, haz clic en Verificar. Cuando RBM verifica tu webhook, se cierra el diálogo.

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 de los mensajes.

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

  1. Extrae el encabezado X-Goog-Signature del mensaje. Esta es una copia con hash y codificación en base64 de la carga útil del cuerpo del mensaje.
  2. Decodifica en base 64 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 configuraste el webhook) como clave, crea un HMAC SHA512 de los bytes de la carga útil del mensaje decodificada en base 64 y codifica el resultado en base 64.
  4. Compara el hash X-Goog-Signature con el hash que creaste.
    • Si los valores hash coinciden, significa que Google envió el mensaje.

    • Si los valores hash no coinciden, verifica el proceso de codificación hash en un mensaje que se sepa que es correcto.

      Si el 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);

Manejo de mensajes

Mostrar cualquier dato que no sea 200 OK desde un webhook se considera un error de 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 garantizar que puedan consumir 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 upstream. Entre los aspectos que debes tener en cuenta, se incluyen los siguientes:

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

Comportamiento en caso de error de publicación

El RBM usa un mecanismo de tiempo de espera y reintento cuando recibe una respuesta distinta de 200 OK de una llamada a webhook. La RBM aumentará el tiempo de espera entre los reintentos hasta un máximo de 600 segundos. Los reintentos continuarán durante 7 días y, luego, se descartará el mensaje.

Implicaciones de los webhooks a nivel del agente

La RBM pone en cola los mensajes de un socio en una cola. Cuando un socio usa webhooks a nivel del agente, es importante tener en cuenta que la falla de uno afectará la entrega a otros. Se llamará a los webhooks que pertenecen a otros agentes durante el período de tiempo de espera de un mensaje con errores. Sin embargo, a medida que los mensajes con errores se ponen en cola para volver a intentarlo, las tasas de entrega generales caerán y otros agentes se verán afectados.

Es importante que los desarrolladores comprendan este modelo y codifiquen según corresponda. En la medida de lo posible, acepta los mensajes y colócalos en una fila para su procesamiento para minimizar la posibilidad de que se produzca un error.

Próximos pasos

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