Webhook

Se necesita ayuda del desarrollador

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

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

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

Nota

Consulta algunos ejemplos de cómo implementar webhooks para diferentes casos de uso y servicios: Muestras de integración de Webhook

Cómo configurar el elemento Webhook

Añadir el elemento Webhook

Arrastra y suelta el elemento Webhook en el lienzo. Coloca el Webhook donde quieras, teniendo en cuenta qué información del Journey vas a enviar a un servicio de terceros.

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

En el campo STEP NAME, introduce 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, especifica la URL de la solicitud a la que se deben enviar los datos. Junto al campo URL, selecciona el tipo de solicitud en el menú desplegable REQUEST TYPE: GET o POST.

Nota

La URL debe ser accesible públicamente. Pushwoosh rechaza direcciones privadas, internas, de bucle local y de enlace local, incluidos los puntos finales de metadatos en la nube, ya sea que provengan de la propia URL o de una redirección a la que apunte. Consulta Tiempos de espera, reintentos y solicitudes fallidas para saber qué sucede cuando se bloquea una solicitud.

Configurar cabeceras

En la sección HEADERS, establece el tipo de contenido.

Por defecto, el tipo de contenido es application/json. Si el servicio al que envías el webhook requiere otro tipo de contenido, introduce 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ñade cabeceras adicionales si es necesario haciendo clic en + ADD HEADER. Puedes eliminar cualquier cabecera haciendo clic en el icono ‘x’ que aparece junto a ella.

Añade cualquier cabecera de autenticación que tu punto final requiera, 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 puedes restringir el punto final a las direcciones IP de Pushwoosh en lugar de, o además de, un secreto de cabecera. Consulta Direcciones IP de Pushwoosh.

Nota

¿Necesitas pasar un valor por usuario, como un token o un ID, en lugar de un secreto fijo? Inserta 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 tu punto final lea.

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

1. Abre un editor de texto plano y escribe tu nombre de usuario y contraseña sin espacios, separados por dos puntos. Por ejemplo: <username>:<password>
2. Codifica esta cadena en Base64.
3. Copia la cadena Base64 resultante (por ejemplo, <base64-encoded-string>).
4. En la configuración del webhook, añade una cabecera de Autorización con el valor: Basic <base64-encoded-string>. Asegúrate de que haya un espacio después de la palabra “Basic”.

Marcar el valor de una cabecera como secreto

Haz clic en el icono del ojo junto al valor de una cabecera para enmascararlo. Pushwoosh oculta ese valor en todos los lugares donde de otro modo saldría del servicio: en la interfaz de usuario, en las respuestas de la API y en el historial de versiones del Journey.

• Enmascaramiento automático. Las cabeceras cuyos nombres parecen credenciales se enmascaran automáticamente, incluso si nunca haces clic en el icono del ojo. Esto incluye Authorization, Proxy-Authorization, Cookie, Set-Cookie y cualquier nombre que contenga token, secret, password, credential, auth o api-key/api_key/apikey (con un guion, un guion bajo o sin separador).
• Cambiar un valor enmascarado. Haz clic en el campo que muestra •••••••• y escribe el nuevo valor. No hay un botón para revelar el valor almacenado. El icono del ojo permanece bloqueado mientras se muestra la máscara. Para eliminar la marca de secreto de una cabecera, primero escribe un nuevo valor y luego haz clic en el icono.
• Renombrar una cabecera enmascarada. Renombrar una cabecera cuyo valor se muestra actualmente como la máscara borra ese valor. Introdúcelo de nuevo con el nuevo nombre. Renombrar una cabecera que actualmente contiene un valor que acabas de escribir mantiene ese valor.

Nota

En el historial de versiones del Journey, un cambio en el valor de una cabecera secreta muestra la máscara en ambos lados de la diferencia. Puedes saber que una cabecera secreta ha cambiado, pero no desde qué o hacia qué ha cambiado.

Añadir el cuerpo de la solicitud JSON

En la sección DATA, introduce el cuerpo de tu solicitud JSON. Asegúrate de que el cuerpo de la solicitud esté en el formato JSON correcto.

Nota

Si no hay valor para el marcador de posición de Datos Dinámicos cuando se envía la solicitud, Pushwoosh envía una cadena vacía en su lugar.

Ejemplo:

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

Usar datos dinámicos y macros

El panel DATA BUILDER te permite insertar información dinámica (como datos de usuario, dispositivo, Tag o evento) directamente en el cuerpo de tu solicitud JSON. Con los Datos Dinámicos, puedes incluir valores específicos para el usuario individual que progresa a través del Journey.

Para ello:

1. Selecciona una categoría. Puedes obtener datos de tres categorías:

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

• Tag: Usa los datos de Tag cuando quieras enviar información almacenada en el perfil del usuario.

• Evento: Usa 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. Selecciona un parámetro (por ejemplo, HWID, categoría favorita, etc.).
3. Pushwoosh genera una macro que se ve así:

{{tag:Language}}

4. Copia la macro y pégala en tu cuerpo JSON en la sección DATA.

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

Escribir marcadores de posición adicionales manualmente

Un marcador de posición es una macro que escribes a mano en lugar de generarla desde una categoría del DATA BUILDER. El panel DATA BUILDER solo cubre datos de Dispositivo, Tag y Evento. Escribe estos marcadores de posición directamente en las secciones URL, HEADERS o DATA. No aparecen en el panel:

Marcador de posición	Valor
{{application_code}}	El código de aplicación de la aplicación a la que pertenece el viajero.
{{traveler:id}}	El ID que Pushwoosh asigna a este viajero para esta ejecución del Journey.
{{journey:uuid}}	El UUID de este Journey.
{{journey:name}}	El nombre de este Journey.
{{point:uuid}}	El UUID de este paso de Webhook.
{{point:name}}	El STEP NAME de este paso de Webhook.
{{event:name}}	El nombre del evento que desencadenó la entrada de este viajero en el Journey.
{{device:platform}}	La plataforma del dispositivo, por ejemplo Android o iOS.
{{device:push_subscribed}}	Si el viajero está suscrito a notificaciones push — true o false.
{{now}}	La fecha y hora actuales, ISO 8601, UTC.
{{now:unix_ms}}	La hora actual en milisegundos Unix.
{{tags:all}}	Cada valor de Tag para el dispositivo del viajero, como un solo objeto JSON. Úsalo sin comillas, por ejemplo "user_properties": {{tags:all}}. Ponerlo entre comillas convierte el objeto en una cadena de texto escapada.

Nota

Un marcador de posición mal escrito, o que no está en esta lista o en el DATA BUILDER, se envía al punto final exactamente como se escribió, llaves incluidas. No hay un banner de error para ello. Revisa el cuerpo de la solicitud en el Registro de llamadas si falta un valor que esperabas.

Mantener el tipo de un marcador de posición en el cuerpo JSON

Un marcador de posición entre comillas siempre se convierte en una cadena de texto JSON, sin importar el tipo de valor que sea en realidad. El mismo marcador de posición por sí solo, sin comillas a su alrededor, mantiene el tipo propio del valor: un número sigue siendo un número, true/false sigue siendo un booleano y una lista se convierte en un array JSON. Un marcador de posición sin comillas debe ser el valor completo del campo — "age": {{tag:Age}} funciona, pero "note": prefix{{tag:Age}}suffix no, porque todo lo que está fuera de las comillas se escribe exactamente como se ha tecleado y los caracteres adicionales rompen el JSON.

{
  "age": {{tag:Age}},
  "age_as_text": "{{tag:Age}}"
}

Aquí age envía el valor numérico del Tag (34), mientras que age_as_text envía la cadena de texto "34". Usa el que espere el campo en el extremo receptor. Si el Tag no tiene valor, un marcador de posición sin comillas se resuelve como una cadena vacía, no como un número o false. Consulta la nota en Añadir el cuerpo de la solicitud JSON.

Precaución

Un marcador de posición de fecha se representa de manera diferente según dónde lo coloques. Entre comillas, mantiene el formato YYYY-MM-DD HH:MM:SS que las integraciones existentes ya analizan. Sin comillas, es ISO 8601, por ejemplo 2026-09-15T08:24:00Z. Los dos no son intercambiables. Elige la posición que coincida con el formato esperado de tu punto final.

Mapear datos de respuesta de webhook a variables

Además de enviar datos, el paso Webhook puede guardar valores de la respuesta que tu servicio envía. Le das a cada valor un nombre (Atributo). Los pasos posteriores pueden usar ese nombre de la misma manera que usan otros valores de respuesta de webhook. Por ejemplo, establece un Tag con Actualizar perfil de usuario, o programa un Retraso de Tiempo a partir de una fecha que el servicio devolvió. Para un ejemplo completo de Journey, consulta Uso de datos de respuesta de webhook en tu Journey.

Ejemplo: el CRM devuelve un ID de usuario. Lo almacenas como Atributo crm_user_id. Luego, Actualizar perfil de usuario lo escribe en un Tag.

Antes de mapear nada, obtén una respuesta de muestra del servicio. Pregúntale a tu desarrollador, o abre una llamada exitosa en el Registro de llamadas después de una prueba y mira el cuerpo de la respuesta. Necesitas los nombres de los campos de esa respuesta para construir la Ruta.

En la sección RESPONSE MAPPING, haz clic en + ADD MAPPING y rellena dos campos por cada valor que quieras capturar:

• Ruta: la ubicación del valor dentro del cuerpo JSON de la respuesta, con puntos entre niveles
• Atributo: el nombre que usarás más adelante en el Journey

Por ejemplo, si tu CRM responde con:

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

1. Establece la Ruta a data.user.id.
2. Establece el Atributo a crm_user_id.

Después de que un usuario pase este paso, los elementos posteriores pueden elegir el Atributo crm_user_id de la misma manera que eligen otros valores de respuesta de webhook.

División de condición no puede usarlos directamente. Los valores de webhook mapeados no tienen tipo. Guarda primero el valor como un Tag y luego bifurca en ese Tag. Consulta Comparar un valor de webhook en División de condición.

Precaución

Si la respuesta es mayor de 64 KB, no se mapea nada de ella. Mantén la respuesta que tu punto final envía razonablemente pequeña si planeas mapear valores de ella.

Para un solo campo, la Ruta y los valores funcionan así:

Nota

• Escribe los nombres de los objetos con puntos: data.user.id.
• Para una lista, usa un número de posición para tomar un elemento. El primer elemento es 0, por lo que results.0.code es el campo code del primer elemento. Para mapear cada elemento de una lista, consulta Mapear cada elemento de un array.
• No puedes mapear solo algunos elementos de una lista. Para una lista es una posición o todos los elementos.
• Pushwoosh mantiene el valor tal como lo envió el servicio (texto, número o verdadero/falso). Un número 100 sigue siendo un número. El texto "100" sigue siendo texto y no funcionará donde el Journey espera un número. Para una fecha de Retraso de Tiempo, el servicio debe devolver un formato que Retraso de Tiempo acepte. Un decimal como 19.99 puede ir a un Tag del tipo Precio.
• Si la respuesta no es un JSON válido, o la Ruta no coincide con ningún campo, ese atributo no se crea para este usuario. El paso de Webhook finaliza como de costumbre. No hay un banner de error. Revisa el cuerpo de la respuesta en el Registro de llamadas y corrige la Ruta si el valor falta más adelante.

Mapear cada elemento de un array

A veces, una respuesta de webhook no tiene un solo valor. Tiene una lista, como cada producto en un pedido, cada artículo en un carrito o cada resultado de una búsqueda. El mapeo de respuestas normalmente captura un valor por campo, por lo que sin esto solo obtendrías un valor mapeado de esa lista, y el resto se perdería.

Pon * en el campo Ruta donde está la lista. Pushwoosh entonces toma un valor de cada elemento de la lista, no solo de una posición. Por ejemplo, si la lista se llama items y cada elemento tiene item_name, establece la Ruta a items.*.item_name.

En RESPONSE MAPPING, haz clic en + ADD MAPPING y rellena los dos campos como de costumbre, con * marcando la lista:

• Ruta: la ubicación del valor dentro de la respuesta, con * donde está la lista. Ejemplo: items.*.item_name.
• Atributo: el nombre que usarás más tarde. Lo que escribas aquí decide cómo obtendrás los resultados:
  • Incluye {n} en el nombre, por ejemplo item_{n}, para obtener cada elemento como su propio valor, numerado desde 1: item_1, item_2, item_3, y así sucesivamente. {n} puede estar en cualquier parte del nombre, por ejemplo item_{n}_sku.
  • Omite {n}, por ejemplo item_names, para unir todos los elementos en un solo valor, separados por comas: Sofa, Lamp, Rug.

Las posiciones de la lista en la Ruta comienzan en 0 (items.0.item_name es el primer elemento). Los nombres de Atributo construidos con {n} comienzan en 1 (item_1 es ese primer elemento). Son dos numeraciones diferentes.

Si solo necesitas un elemento de la lista, usa un número en la Ruta en lugar de *, por ejemplo items.0.item_name.

Ejemplo

Si tu CRM responde con:

{
  "items": [
    { "item_name": "Sofa" },
    { "item_name": "Lamp" },
    { "item_name": "Rug" }
  ]
}

• Establece la Ruta a items.*.item_name y el Atributo a item_{n} para obtener tres valores separados: item_1 es Sofá, item_2 es Lámpara, item_3 es Alfombra.
• Establece el Atributo a item_names para obtener un solo valor: item_names es Sofa, Lamp, Rug.

Nota

Si a un elemento de la lista le falta el campo que buscas (por ejemplo, no tiene item_name), ese elemento se omite. La numeración no deja un hueco para él. Ejemplo: tres filas donde la del medio no tiene item_name se convierten solo en item_1 y item_2.

Solo se capturan los primeros 50 elementos de una lista. Cualquier cosa más allá de eso se descarta. El viajero continúa en el Journey. Solo faltan los valores no mapeados.

Puedes usar los valores mapeados más adelante en el Journey como cualquier otro atributo de respuesta de webhook:

• Actualizar perfil de usuario: guarda un valor en un Tag
• Retraso de Tiempo: espera hasta una fecha de la respuesta
• Contenido Dinámico: personaliza el contenido del mensaje

División de condición no puede usarlos directamente. Los valores de webhook mapeados no tienen tipo. Guarda primero el valor como un Tag y luego bifurca en ese Tag. Consulta Comparar un valor de webhook en División de condición.

Uso de datos de respuesta de webhook en tu Journey

Tiempos 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.

Reintentos

En una respuesta 500, 502, 503 o 504, o un error de red como un fallo de conexión, Pushwoosh reintenta la solicitud una vez antes de rendirse. Una solicitud que agota el tiempo de espera no se reintenta — consulta Qué sucede cuando una solicitud falla a continuación. Cualquier otra respuesta que no sea 2xx tampoco se reintenta.

Nota

Un reintento vuelve a enviar exactamente la misma solicitud. Haz que tu punto final sea seguro para recibir la misma llamada dos veces (idempotente) si un duplicado sería un problema, por ejemplo, cobrar un pago o crear un registro dos veces.

Límites de tasa

Pushwoosh limita cuántas solicitudes de webhook puede enviar una cuenta por segundo. El límite está dimensionado muy por encima de los picos de tráfico reales, por lo que los Journeys normales no se ven afectados. Una ráfaga que lo excede espera brevemente a que haya espacio antes de fallar.

Enfriamiento del punto final

Si un punto final falla varias veces seguidas, Pushwoosh deja de enviarle solicitudes durante un tiempo en lugar de reintentar un punto final roto en cada viajero, comenzando en 30 segundos y duplicándose en fallos posteriores hasta 5 minutos. Una sola solicitud exitosa borra esto y reanuda la entrega normal.

Qué sucede cuando una solicitud falla

El elemento Webhook no tiene una rama separada para solicitudes fallidas. Cualquiera de los siguientes casos elimina al viajero del Journey en este paso:

Causa	Qué lo desencadena
Dirección de punto final bloqueada	La URL es privada, interna, de bucle local o de enlace local, incluidos los puntos finales de metadatos en la nube
Límite de tasa	Se excede el límite de solicitudes de webhook por segundo de la cuenta y no se abre espacio durante la breve espera
Enfriamiento del punto final	El punto final falló varias veces seguidas y Pushwoosh lo está omitiendo temporalmente
Tiempo de espera agotado	Sin respuesta en 10 segundos, o el paso excede su límite de 30 segundos
Error de red	La solicitud no pudo llegar al punto final en absoluto
Respuesta no 2xx	El punto final devolvió un estado de error que no se reintenta, o se reintentó una vez y volvió a fallar

Consulta Error de solicitud.

Si no puedes permitirte perder viajeros aquí, haz que tu punto final siempre devuelva una respuesta 2xx y pon cualquier estado de fallo en el cuerpo de la respuesta, por ejemplo, como un valor que tu Mapeo de respuesta pueda recoger.

Esto se aplica a cada paso de Webhook, incluidos los creados anteriormente. Una dirección de punto final que ahora coincida con la regla de direcciones bloqueadas anterior comenzará a fallar de la misma manera.

A diferencia de una solicitud fallida, 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. Consulta la nota en Mapeo de respuesta anterior.

Probar el Webhook

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

Si una cabecera todavía muestra la máscara almacenada, Pushwoosh rellena el valor real guardado para la solicitud de prueba. El valor nunca aparece en tu navegador.

Esta sustitución solo funciona para una cabecera ya guardada en este paso exacto. Un paso que aún no has guardado, o uno que acabas de copiar, no tiene ningún valor guardado detrás de la máscara, por lo que Pushwoosh envía la solicitud de prueba sin esa cabecera.

Después de una prueba exitosa (o una llamada en vivo), abre el Registro de llamadas, expande la fila y compara el cuerpo de la respuesta con cada Ruta. El campo debe existir exactamente como en la Ruta. Si la solicitud tiene éxito pero un paso posterior no tiene valor, la Ruta generalmente no coincide con la respuesta. El paso de Webhook no mostrará un error por eso.

Guardar tu configuración

Haz clic en Guardar para guardar la configuración de tu webhook.

Registro de llamadas

Abre la pestaña Registro de llamadas en el panel del punto para ver lo que Pushwoosh realmente envió para este paso: hora, usuario, resultado y duración, retrocediendo 30 días.

Nota

El Registro de llamadas solo registra las solicitudes que Pushwoosh realmente envió. Un viajero que fue eliminado antes de ese punto, por ejemplo por el límite de tasa o un enfriamiento del punto final, no obtiene una fila aquí.

Filtra por resultado (Éxito, Error HTTP, Sin respuesta) o busca por el User ID o HWID exacto. Haz clic en una fila para expandirla y ver la solicitud (método, URL y cuerpo) y, dependiendo del resultado, la respuesta (estado y cuerpo) o el texto del error. La Duración cubre todo el paso, incluido el tiempo empleado en un reintento automático.

Precaución

Los cuerpos de solicitud y respuesta de más de 4 KB se cortan, marcados con …[truncated]. Cualquier valor que Pushwoosh haya enviado en una cabecera, como un token de portador o una clave de API, se reemplaza con [redacted] en todos los lugares donde aparecería: en la URL, los cuerpos y el texto de error, no solo en un campo de cabeceras.