Webhook

Se necesita la ayuda de un desarrollador

Necesitará la ayuda de su equipo de desarrolladores para configurar el elemento Webhook. Comparta esta guía con ellos para empezar.

Los webhooks le permiten enviar datos de Journey a servicios externos como sistemas de análisis, CRM y herramientas de marketing. Puede:

• Notificar a sistemas externos cuando un cliente realiza una acción en el Journey
• Enviar datos de clientes a herramientas de análisis
• Activar correos electrónicos, SMS o WhatsApp de terceros en eventos específicos del Journey

Nota

Consulte algunos ejemplos de cómo implementar webhooks para diferentes casos de uso y servicios: Ejemplos de integración de webhooks

Cómo configurar el elemento Webhook

Añadir el elemento Webhook

Arrastre y suelte el elemento Webhook en el lienzo. Coloque el Webhook en cualquier lugar que desee, teniendo en cuenta qué información del Journey va a enviar a un servicio de terceros.

Nombrar el paso del Webhook y especificar la URL y el tipo de solicitud

En el campo NOMBRE DEL PASO, introduzca un nombre para el webhook. Puede ser útil nombrar los webhooks según los servicios a los que envían datos o el caso de uso.

A continuación, en el campo URL, especifique la URL de la solicitud a la que se deben enviar los datos. Junto al campo URL, seleccione el tipo de solicitud en el menú desplegable TIPO DE SOLICITUD: GET o POST.

Configurar las cabeceras

En la sección CABECERAS, establezca el tipo de contenido.

Por defecto, el tipo de contenido es application/json. Si el servicio al que envía el webhook requiere otro tipo de contenido, introduzca el apropiado en el valor de la cabecera Content-Type.

Ejemplos de tipos de contenido son:

• x-www-form-urlencoded
• text/plain
• text/xml

Añada cabeceras adicionales si es necesario haciendo clic en + AÑADIR CABECERA. Puede eliminar cualquier cabecera haciendo clic en el icono ‘x’ que aparece junto a ella.

Añada cualquier cabecera de autenticación que requiera su endpoint, por ejemplo:

• Authorization: Bearer <token>
• X-Api-Key: <key>
• Authorization: Basic <base64(user:pass)>

Solo se admite un secreto estático en una cabecera. Los flujos de intercambio de tokens OAuth2, mTLS y la firma de solicitudes por parte de Pushwoosh no son compatibles. También puede restringir el endpoint a las direcciones IP de Pushwoosh en lugar de, o además de, un secreto de cabecera. Consulte Direcciones IP de Pushwoosh.

Nota

¿Necesita pasar un valor por usuario, como un token o un ID, en lugar de un secreto fijo? Inserte una macro de Datos Dinámicos en la URL o en el cuerpo JSON, por ejemplo como un parámetro de consulta o un campo del cuerpo que su endpoint lea.

Para la autenticación HTTP Basic específicamente, haga lo siguiente:

1. Abra un editor de texto plano y escriba su nombre de usuario y contraseña sin espacios, separados por dos puntos. Por ejemplo: myuser:mypass
2. Codifique esta cadena en Base64.
3. Copie la cadena Base64 resultante (por ejemplo, bXl1c2VyOm15cGFzcw==).
4. En la configuración del webhook, añada una cabecera de Autorización con el valor: Basic <SU CADENA BASE64>. Asegúrese de que hay un espacio después de la palabra “Basic”.

Añadir el cuerpo de la solicitud JSON

En la sección DATOS, introduzca el cuerpo de su solicitud JSON. Asegúrese de que el cuerpo de la solicitud está en el formato JSON correcto.

Nota

Si no hay ningún valor para el marcador de posición de Datos Dinámicos cuando se envía la solicitud POST, se transmitirá el valor nulo.

Ejemplo:

{
  "hwid": "{{device:hwid}}"
}

Usar datos dinámicos y macros

El panel CONSTRUCTOR DE DATOS le permite insertar información dinámica (como datos de usuario, dispositivo, etiqueta o evento) directamente en el cuerpo de su solicitud JSON. Con los Datos Dinámicos, puede incluir valores específicos para el usuario individual que progresa a través del Journey.

Para ello:

1. Seleccione una categoría. Puede obtener datos de tres categorías:

• Dispositivo: Utilice los datos del Dispositivo cuando necesite información técnica vinculada al dispositivo del usuario.

• Etiqueta: Utilice los datos de Etiqueta cuando desee enviar información almacenada en el perfil del usuario.

• Evento: Utilice los datos de Evento cuando el webhook deba enviar valores del evento desencadenante del Journey.

Nota

Los valores del evento desencadenante permanecen adjuntos al viajero durante el resto del Journey, incluso a través de un Retraso de tiempo. Solo se pierden si el viajero abandona el Journey, por ejemplo en un evento de cancelación, una salida o cuando el Journey termina. Si un viajero pasa por el mismo paso de Webhook más de una vez, la nueva respuesta sobrescribe el valor que mapeó la última vez.

2. Seleccione un parámetro (por ejemplo, HWID, categoría favorita, etc.).
3. Pushwoosh genera una macro que se ve así:

{{tag:Language}}

4. Copie la macro y péguela en su cuerpo JSON en la sección DATOS.

Cuando el webhook se ejecuta en un Journey en vivo, Pushwoosh reemplaza automáticamente la macro con el valor real para ese usuario.

Mapear los datos de respuesta del webhook a variables

Además de enviar datos, el elemento Webhook también puede capturar datos de la respuesta que recibe y convertirlos en variables. Estas variables pueden ser utilizadas más tarde en el Journey. Por ejemplo, establezca una etiqueta con Actualizar perfil de usuario, o programe un Retraso de tiempo basado en un valor devuelto por el servicio externo. Para un ejemplo completo de Journey, consulte Uso de los datos de respuesta de webhook en su Journey.

En la sección MAPEO DE RESPUESTA, haga clic en + AÑADIR MAPEO y rellene dos campos para cada valor que desee capturar:

• Ruta: la ubicación del valor dentro del cuerpo JSON de la respuesta
• Atributo: el nombre que utiliza para hacer referencia a este valor más adelante en el Journey

Por ejemplo, si su CRM responde con:

{
  "data": {
    "user": {
      "id": "789xyz"
    }
  }
}

Establezca la Ruta en data.user.id y el Atributo en crm_user_id para capturar ese ID.

Nota

Algunas cosas que debe saber sobre el mapeo:

• Ruta es una ruta simple separada por puntos (claves de objeto y, para arrays, índices numéricos, por ejemplo results.0.code). No admite comodines ni filtros, por lo que solo puede apuntar a un valor específico a la vez.
• Los valores se almacenan exactamente como vienen de la respuesta JSON (texto, número o verdadero/falso). No hay conversión de tipo: 100 se mapea como un número, pero "100" se mapea como texto y no funcionará en una comparación numérica. Si planea usar un valor como fecha en un elemento de Retraso de tiempo, asegúrese de que su servicio lo devuelva en uno de los formatos de fecha que admite el Retraso de tiempo. Un número decimal (por ejemplo 19.99) puede guardarse en una Etiqueta del tipo Precio.
• Si la respuesta no es un JSON válido, o una Ruta no coincide con nada, la variable correspondiente no se crea para ese usuario. No se muestra ningún error, y el paso de Webhook se completa normalmente.

Precaución

Los cuerpos de respuesta de más de 64 KB no se procesan para el mapeo en absoluto. Mantenga la respuesta que su endpoint devuelve razonablemente pequeña si planea mapear valores de ella.

Uso de los datos de respuesta de webhook en su Journey

Tiempo de espera, reintentos y solicitudes fallidas

Pushwoosh espera hasta 10 segundos por una respuesta. Todo el paso de Webhook, incluyendo el envío de la solicitud y el procesamiento de la respuesta, tiene un límite de 30 segundos. Cada viajero activa la solicitud una vez, y no hay reintentos automáticos.

Precaución

Un tiempo de espera, un error de red o una respuesta que no sea 2xx elimina al viajero del Journey en este paso, porque el elemento Webhook no tiene una rama separada para dirigir las solicitudes fallidas. Consulte Error de solicitud. Si no puede permitirse perder viajeros aquí, haga que su endpoint siempre devuelva una respuesta 2xx y ponga cualquier estado de fallo en el cuerpo de la respuesta, por ejemplo como un valor que su Mapeo de respuesta pueda recoger.

Esto solo cubre el fallo de la propia solicitud. Una respuesta que llega pero no se mapea limpiamente, como un JSON no válido, una Ruta no resuelta o un cuerpo de más de 64 KB, no elimina al viajero. Consulte la nota en Mapeo de respuesta anterior.

Probar el Webhook

Haga clic en Probar webhook para verificar que la configuración de su webhook es correcta y que la solicitud se envía con éxito.

Guardar su configuración

Haga clic en Aplicar para guardar la configuración de su webhook.