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 tienes claro 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 con 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. Ponle a tu Campaign un nombre claro y significativo.
4. (Opcional) Añade una descripción para explicar cómo se utilizará esta Campaign.
5. Añade equipos y etiquetas según sea necesario.
   • Las etiquetas facilitan la búsqueda de tus campañas y la elaboración de informes. Por ejemplo, al utilizar el generador de informes, puedes filtrar por etiquetas específicas.
6. Añade y nombra tantas variantes como necesites para tu Campaign. 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 Campaign van a ser similares o tener el mismo contenido, redacta tu mensaje antes de añadir variantes adicionales. Luego puedes elegir Copiar de variante en el 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 Compose del editor.

La pestaña Compose 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 Add languages y completa los campos obligatorios.

Te recomendamos seleccionar los idiomas antes de escribir tu contenido para que puedas completar el 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 rendericen los proveedores de servicios. Para conocer las mejores prácticas sobre la creación de mensajes de derecha a izquierda que se muestren con la mayor precisión 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, este debería proporcionarte 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 la solicitud de tu 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 espere 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!. Una vez que hayas introducido tu par clave-valor, el creador configurará tu solicitud en sintaxis JSON y se rellenará 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 espere un cuerpo en cualquier formato. Por ejemplo, podrías usar esto para escribir una solicitud para un endpoint que espere 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 formato de cadena codificada en URL. Por ejemplo:

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

Paso 3: Configurar ajustes adicionales

Encabezados de solicitud (opcional)

Ciertos endpoints pueden requerir que incluyas encabezados en tu solicitud. En la sección Redactar 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 los encabezados HTTP no distinguen entre mayúsculas y minúsculas según 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á el procesamiento de los encabezados: Content-Type, content-type y CONTENT-TYPE se tratan de forma idéntica.

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

Los encabezados de autorización deben usar la clave Authorization. Los valores 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 activar tu campaña, Braze recomienda que pruebes el webhook para asegurarte de que la solicitud tiene el formato correcto.

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 más información, consulta Enviar mensajes de prueba.

Paso 5: Construye el resto de tu Campaign o Canvas

• campaign
• canvas

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

Elige el horario de entrega o el desencadenante

Los webhooks pueden entregarse basándose en un horario programado, una acción o un desencadenante de API. Para más información, consulta Programar tu Campaign.

Para la entrega basada en acciones, también puedes establecer la duración de la Campaign 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 Campaign, o habilitar reglas de limitación de frecuencia.

Elige los usuarios objetivo

A continuación, debes segmentar a los usuarios eligiendo Segments o filtros para acotar tu audiencia. En este paso, seleccionas la audiencia más amplia de tus Segments y la reduces aún más con nuestros filtros, si lo deseas. Recibes automáticamente una vista previa de cómo es aproximadamente la población de ese Segment. Ten en cuenta que la pertenencia exacta al Segment siempre se calcula antes de que se envíe 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 eventos de conversión

Braze te permite hacer seguimiento de la frecuencia con la que los usuarios realizan acciones específicas, eventos de conversión, después de recibir una Campaign. Tienes la opción de permitir una ventana de hasta 30 días durante la cual se contará 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 detalles sobre cómo construir el resto de tu Canvas, incluyendo pruebas multivariante y Optimizar con BrazeAI^TM, consulta Construir tu Canvas.

Paso 6: Revisar e implementar

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

Cosas que debes saber

Errores, lógica de reintento y tiempos de espera

Los webhooks dependen de los servidores de Braze que realizan solicitudes a un endpoint externo, y ocasionalmente pueden ocurrir errores. Los errores más comunes incluyen errores de sintaxis, claves de API expiradas, 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 respecto al origen del error, deberías consultar la documentación del endpoint de API que estás utilizando. Generalmente proporcionan 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 reintento

Cuando se envía la solicitud de webhook, el servidor receptor devolverá un código de respuesta indicando 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 Campaign y si, en caso de errores, Braze intentará reenviar la Campaign:

Nota

Braze reintenta los códigos de estado mencionados anteriormente en esta sección hasta cinco veces en un plazo de 30 minutos utilizando retirada exponencial. Si no podemos alcanzar tu endpoint, los reintentos pueden distribuirse en un periodo de 24 horas.

Cada webhook tiene un tiempo de espera máximo de 90 segundos.

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 Campaign o paso en Canvas. Braze solo reintenta ciertas respuestas (por ejemplo, 408, 429 y 5XX); la mayoría de los otros errores de cliente 4XX, incluido 401 Unauthorized, no se reintentan. Para la tabla completa de respuestas, consulta Códigos de respuesta y lógica de reintento.

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 ausente, 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, añade las IP de Braze a la lista de permitidas de 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 con 4XX, consulta Solución de problemas de solicitudes de webhook y contenido conectado.

Autenticación y credenciales de contenido conectado

La solicitud HTTP de webhook saliente no admite adjuntar credenciales de contenido conectado (:basic_auth o :auth_credentials) para autenticarte contra tu endpoint. En su lugar, configura la autenticación utilizando Encabezados de solicitud en el webhook. 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 la resuelva antes de que se envíe el webhook.

Plantillas de webhook guardadas y uso en Campaigns

Braze no proporciona un informe integrado que liste cada Campaign o paso en Canvas que haga referencia a una plantilla de webhook guardada determinada. Para auditar el uso, revisa los pasos de webhook que utilicen la misma URL y método HTTP, o contacta 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 para resolver errores específicos de webhook, consulta Solución de 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 en mal estado y cómo Braze proporciona notificaciones de errores a través de correos electrónicos automatizados y registros adicionales 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 listadas se añaden automática y dinámicamente a cualquier clave de API que haya sido incluida en la lista de permitidas.

Importante

Si estás realizando un webhook de Braze a Braze y utilizas listas de permitidas, deberías incluir todas las siguientes IP, incluida 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.