Crear una campaña de webhook

Crear una campaña de webhook o incluir un webhook en una campaña multicanal te permite desencadenar acciones fuera de la aplicación proporcionando a otros sistemas y aplicaciones información en tiempo real.

Puedes usar webhooks para enviar información a sistemas como Salesforce o Marketo, o a tus sistemas backend. Por ejemplo, podrías querer acreditar en las cuentas de tus clientes una promoción después de que hayan realizado un evento personalizado un determinado número de veces.

Consejo

Para obtener más información sobre qué son los webhooks y cómo puedes usarlos en Braze, consulta Webhooks antes de continuar.

Paso 1: Elige dónde crear tu mensaje

¿No estás seguro de si tu mensaje debe enviarse mediante una Campaign o un Canvas? Las Campaigns son mejores para campañas de mensajería únicas y segmentadas, mientras que los Canvas son mejores para recorridos de usuario de varios pasos.

• campaign
• canvas

Pasos:

1. Ve a Mensajería > Campaigns y selecciona Crear Campaign.
2. Selecciona Webhook o, para campañas dirigidas a múltiples canales, selecciona Multicanal.
3. Dale a tu campaña un nombre claro y significativo.
4. (Opcional) Añade una descripción para explicar cómo se utilizará esta campaña.
5. Añade equipos y etiquetas según sea necesario.
   • Las etiquetas facilitan encontrar tus campañas y generar informes a partir de ellas. Por ejemplo, al usar el generador de informes, puedes filtrar por etiquetas específicas.
6. Añade y nombra tantas variantes como necesites para tu campaña. Puedes elegir diferentes plantillas de webhook para cada una de las variantes añadidas. Para más información sobre este tema, consulta Pruebas multivariante y A/B.

Consejo

Si todos los mensajes de tu campaña van a ser similares o tienen el mismo contenido, redacta tu mensaje antes de añadir variantes adicionales. Luego puedes elegir Copiar de variante en el menú desplegable Añadir variante.

Pasos:

1. Crea tu Canvas usando el creador de Canvas.
2. Después de configurar tu Canvas, añade un paso en el constructor de Canvas. Asigna a tu paso un nombre claro y significativo.
3. Elige un horario de paso y especifica un retraso según sea necesario.
4. Filtra tu audiencia para este paso según sea necesario. Puedes refinar aún más los destinatarios de este paso especificando segmentos y añadiendo filtros adicionales. Las opciones de audiencia se verificarán después del retraso en el momento en que se envíen los mensajes.
5. Elige tu comportamiento de avance.
6. Elige cualquier otro canal de mensajería que desees combinar con tu mensaje.

Paso 2: Crea tu webhook

Puedes elegir crear un webhook desde cero, usar una plantilla existente o usar una de nuestras plantillas existentes. Luego, crea tu webhook en la pestaña Redactar del editor.

La pestaña Redactar consta de los siguientes campos:

• Idioma
• URL del webhook
• Método HTTP
• Cuerpo de la solicitud

Idioma

La internacionalización es compatible con la URL y el cuerpo de la solicitud. Para internacionalizar tu mensaje, selecciona Añadir idiomas y rellena los campos obligatorios.

Te recomendamos seleccionar tus idiomas antes de redactar tu contenido para que puedas completar tu texto donde corresponda en Liquid. Para consultar nuestra lista completa de idiomas disponibles, consulta Idiomas compatibles.

Si estás añadiendo texto en un idioma que se escribe de derecha a izquierda, ten en cuenta que la apariencia final de los mensajes de derecha a izquierda depende en gran medida de cómo los proveedores de servicios los representan. Para conocer las mejores prácticas sobre cómo crear mensajes de derecha a izquierda que se muestren de la manera más precisa posible, consulta Creación de mensajes de derecha a izquierda.

URL del webhook

La URL del webhook, o URL HTTP, especifica tu endpoint. El endpoint es el lugar donde enviarás la información que estás capturando en el webhook.

Si deseas enviar información a un proveedor, el proveedor debería proporcionar esta URL en su documentación de API. Si estás enviando información a tus propios sistemas, consulta con tu equipo de desarrollo o ingeniería para confirmar que estás usando la URL correcta.

Braze solo permite URLs que se comuniquen a través de los puertos estándar 80 (HTTP) y 443 (HTTPS).

Uso de Liquid

Puedes personalizar las URLs de tu webhook usando Liquid. A veces, ciertos endpoints pueden requerir que identifiques a un usuario o proporciones información específica del usuario como parte de tu URL. Al usar Liquid, asegúrate de incluir un valor predeterminado para cada dato específico del usuario que utilices en tu URL.

Método HTTP

El método HTTP que debes usar varía según el endpoint al que estés enviando información. En la mayoría de los casos, usarás POST.

Cuerpo de la solicitud

El cuerpo de la solicitud es la información que se enviará a la URL que especificaste. Puedes crear el cuerpo de tu solicitud de webhook con pares clave-valor JSON o texto sin formato.

Pares clave-valor JSON

Los pares clave-valor JSON te permiten escribir fácilmente una solicitud para un endpoint que espera un formato JSON. Solo puedes usar esto con un endpoint que espere una solicitud JSON. Por ejemplo, si tu clave es message_body, el valor correspondiente podría ser Your order just arrived!. Después de ingresar tu par clave-valor, el creador configurará tu solicitud en sintaxis JSON, y se generará automáticamente una vista previa de tu solicitud JSON.

Puedes personalizar tus pares clave-valor usando Liquid, incluyendo cualquier atributo de usuario, atributo personalizado o propiedad de evento en tu solicitud. Por ejemplo, puedes incluir el nombre y el correo electrónico de un cliente en tu solicitud. Asegúrate de incluir un valor predeterminado para cada atributo.

Texto sin formato

La opción de texto sin formato te da la flexibilidad de escribir una solicitud para un endpoint que espera un cuerpo en cualquier formato. Por ejemplo, podrías usar esto para escribir una solicitud para un endpoint que espera que tu solicitud esté en formato XML.

Tanto la personalización como la internacionalización usando Liquid son compatibles con el texto sin formato.

Si configuras el encabezado de solicitud Content-Type como application/x-www-form-url-encoded, el cuerpo de la solicitud debe tener el formato de una cadena codificada como URL. Por ejemplo:

1
to={{custom_attribute.${example}}}&text=Your+order+just+arrived

Paso 3: Configura ajustes adicionales

Encabezados de solicitud (opcional)

Ciertos endpoints pueden requerir que incluyas encabezados en tu solicitud. En la sección Crear del creador, puedes añadir tantos encabezados como necesites.

Los encabezados de solicitud más comunes son las especificaciones de Content-Type (que describen qué tipo de datos esperar en el cuerpo, como XML o JSON) y los encabezados de Authorization que contienen tus credenciales con tu proveedor o sistema.

Nota

Los nombres de encabezados HTTP no distinguen entre mayúsculas y minúsculas según la RFC 7230, sección 3.2 (“Each header field consists of a case-insensitive field name”). Si tu endpoint receptor o cualquier servicio intermedio (como CDN) transforma las mayúsculas y minúsculas de los encabezados, esto no afectará al procesamiento de los encabezados: Content-Type, content-type y CONTENT-TYPE se tratan de forma idéntica.

Las especificaciones de tipo de contenido deben utilizar la clave Content-Type. Los valores más comunes son application/json o application/x-www-form-urlencoded.

Los encabezados de autorización deben utilizar la clave Authorization. Los valores más comunes son Bearer {{YOUR_TOKEN}} o Basic {{YOUR_TOKEN}} donde YOUR_TOKEN son las credenciales proporcionadas por tu proveedor o sistema.

Paso 4: Envío de prueba de tu mensaje

Antes de que tu campaña entre en funcionamiento, Braze recomienda que pruebes el webhook para asegurarte de que la solicitud tiene el formato adecuado.

Para hacerlo, cambia a la pestaña Prueba y envía un webhook de prueba. Puedes probar el webhook como un usuario aleatorio, un usuario específico (introduciendo su dirección de correo electrónico o ID de usuario externo), o un usuario personalizado con los atributos que elijas.

Después de enviar el webhook de prueba, aparecerá un cuadro de diálogo con el mensaje de respuesta. Si la solicitud del webhook no tiene éxito, consulta el mensaje de error para obtener ayuda en la solución de problemas de tu webhook. El siguiente ejemplo detalla la respuesta de un webhook con una URL de webhook no válida.

1
2
3
4
5
6
7
8
9
404 Not Found

{
  "error": {
    "message": "Unrecognized request URL. Please see https://lob.com/docs or email us at [email protected].",
    "status_code": 404
  }
}

Para obtener más información, consulta Enviar mensajes de prueba.

Paso 5: Construye el resto de tu campaña o Canvas

• campaign
• canvas

A continuación, construye el resto de tu campaña. Consulta las siguientes secciones para obtener más detalles sobre cómo utilizar mejor nuestras herramientas para crear webhooks.

Elige el calendario de entrega o el desencadenante

Los webhooks se pueden entregar en función de un horario programado, una acción o un desencadenante de API. Para más información, consulta Programar tu campaña.

Para la entrega basada en acciones, también puedes establecer la duración de la campaña y las horas tranquilas.

En este paso también puedes especificar controles de entrega, como permitir que los usuarios vuelvan a ser elegibles para recibir la campaña, o habilitar reglas de limitación de frecuencia.

Elige los usuarios a los que dirigirte

A continuación, debes dirigirte a los usuarios eligiendo segmentos o filtros para acotar tu audiencia. En este paso, seleccionas la audiencia más amplia de tus segmentos y la reduces aún más con nuestros filtros, si lo deseas. Recibirás automáticamente una vista previa de cómo se ve la población aproximada de ese segmento. Ten en cuenta que la pertenencia exacta al segmento siempre se calcula antes de enviar el mensaje.

Importante

Tu mensaje solo se enviará a los usuarios que ya cumplan las condiciones que estableciste en el paso Público objetivo. Después de eso, aún deben cumplir con el desencadenante que definas en el paso Planificación de entrega. Piensa en la audiencia objetivo como una sala de espera: solo las personas que ya están dentro pueden avanzar cuando se produce la siguiente acción.

Elige los eventos de conversión

Braze te permite hacer un seguimiento de la frecuencia con la que los usuarios realizan acciones específicas, eventos de conversión, después de recibir una campaña. Tienes la opción de permitir una ventana de hasta 30 días durante la cual se contabilizará una conversión si el usuario realiza la acción especificada.

Si aún no lo has hecho, completa las secciones restantes de tu paso en Canvas. Para obtener más detalles sobre cómo construir el resto de tu Canvas, incluidas las pruebas multivariante y Optimizar con BrazeAI^TM, consulta Construir tu Canvas.

Paso 6: Revisa e implementa

Cuando hayas terminado de crear la última de tus Campaign o Canvas, revisa los detalles, pruébala y envíala.

Cosas que debes saber

Errores, lógica de reintentos y tiempos de espera

Los webhooks dependen de que los servidores de Braze realicen solicitudes a un endpoint externo, y pueden producirse errores ocasionalmente. Los errores más comunes incluyen errores de sintaxis, claves de API caducadas, límites de velocidad y problemas inesperados del lado del servidor. Antes de enviar una campaña de webhook:

• Prueba tu webhook en busca de errores de sintaxis
• Asegúrate de que las variables personalizadas tengan valores predeterminados

Si tu webhook no se envía, se registra un mensaje de error en el Registro de actividad de mensajes, e incluye detalles como la marca de tiempo del error, el nombre de la aplicación y detalles sobre el error.

Si el mensaje de error no es lo suficientemente claro sobre el origen del error, deberías consultar la documentación del endpoint de API que estás utilizando. Estas suelen proporcionar una explicación de los códigos de error que utiliza el endpoint, así como las causas habituales.

Códigos de respuesta y lógica de reintentos

Cuando se envía la solicitud del webhook, el servidor receptor devuelve un código de respuesta que indica qué ocurrió con la solicitud. La siguiente tabla resume las diferentes respuestas que el servidor puede enviar, cómo afectan a los análisis de la campaña y si, en caso de errores, Braze intentará volver a entregar la campaña:

Nota

Braze reintenta los códigos de estado reintentables en esta sección hasta un total de cinco intentos (la solicitud inicial más cuatro reintentos), con un retraso creciente entre intentos. Si Braze no puede alcanzar tu endpoint, los reintentos pueden continuar hasta por 24 horas.

Cada solicitud de webhook tiene un tiempo límite de 120 segundos antes de que se agote.

Los encabezados de respuesta Retry-After y de límite de velocidad pueden afectar cuánto tiempo espera Braze antes de un intento reintentable (por ejemplo, después de 408, 429 o 5XX). No hacen que las respuestas no reintentables, como 401, sean elegibles para reintento.

Nota

Si los envíos de webhook parecen estar ausentes en los análisis, abre el Registro de actividad de mensajes para la campaña o el paso en Canvas. Braze solo reintenta ciertas respuestas (por ejemplo, 408, 429 y 5XX): la mayoría de los otros errores de cliente 4XX, incluyendo 401 Unauthorized, no se reintentan. Para la tabla completa de respuestas, consulta Códigos de respuesta y lógica de reintentos.

403 Forbidden y listas de IP permitidas {#403-forbidden-and-ip-allowlisting}

Las respuestas 403 Forbidden significan que tu endpoint recibió la solicitud pero la rechazó. Las causas comunes incluyen autenticación inválida o faltante, permisos de API insuficientes y reglas de red (como un firewall o un firewall de aplicaciones web) que bloquean las direcciones IP de salida de Braze.

Si las solicitudes de webhook devuelven consistentemente 403 y tus encabezados de autenticación son correctos, incluye en la lista de permitidas las IP de Braze para tu clúster en el servidor que recibe el webhook. Consulta Listas de IP permitidas. Las solicitudes de contenido conectado utilizan las mismas IP de salida; consulta Listas de IP permitidas de contenido conectado.

Para otros pasos de solución de problemas 4XX, consulta Solucionar problemas de solicitudes de webhook y contenido conectado.

Autenticación y credenciales de contenido conectado

La solicitud HTTP del webhook de salida no admite adjuntar credenciales de contenido conectado (:basic_auth o :auth_credentials) para autenticarse contra tu endpoint. Configura la autenticación utilizando Encabezados de solicitud en el webhook en su lugar. Para obtener un token o secreto en el momento del envío, puedes colocar una etiqueta {% connected_content %} en un campo de encabezado o cuerpo para que Liquid lo resuelva antes de que se envíe el webhook.

Plantillas de webhook guardadas y uso en Campaigns

Braze no proporciona un informe incorporado que enumere cada campaña o paso en Canvas que haga referencia a una plantilla de webhook guardada determinada. Para auditar el uso, revisa los pasos de webhook que utilizan la misma URL y método HTTP, o ponte en contacto con soporte de Braze.

Solución de problemas y detalles adicionales de errores

Para explicaciones detalladas, pasos de solución de problemas y orientación sobre cómo resolver errores específicos de webhook, consulta Solucionar problemas de solicitudes de webhook y contenido conectado. También encontrarás más explicaciones sobre cómo funciona nuestro sistema de detección de hosts no saludables y cómo Braze proporciona notificaciones de errores a través de correos electrónicos automatizados y registro adicional en Braze Currents.

Listas de IP permitidas

Cuando se envía un webhook desde Braze, los servidores de Braze realizan solicitudes de red a los servidores de nuestros clientes o de terceros. Con las listas de IP permitidas, puedes verificar que las solicitudes de webhook provienen de Braze, añadiendo una capa de seguridad.

Braze enviará webhooks desde las siguientes IP. Las IP enumeradas se añaden de forma automática y dinámica a cualquier clave de API que se haya habilitado para la lista de permitidas.

Importante

Si estás realizando un webhook de Braze a Braze y utilizas listas de permitidas, deberías incluir en la lista todas las siguientes IP, incluyendo 127.0.0.1.

• united states (us)
• european union (eu)
• australia (au)
• indonesia (id)
• japan (jp)
• south korea (kr)

Eliminar usuarios

Para eliminar un usuario individual o un Segment de usuarios, ve a Audiencia > Gestionar audiencia > Eliminar usuarios. El panel admite la eliminación masiva de Segments (hasta 10 millones de perfiles), incluye una ventana de cancelación de 7 días y no consume los límites de velocidad compartidos de la REST API. Para los pasos, límites y permisos, consulta Eliminar usuarios.

Para la eliminación programática en lotes más pequeños, utiliza el endpoint /users/delete en lugar de una campaña de webhook.