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 describir cómo se utilizará esta campaña.
5. Añade equipos y etiquetas según sea necesario.
   • Las etiquetas facilitan la búsqueda de tus campañas y la creación de informes. 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 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. Después, crea tu webhook en la pestaña Redactar del editor.

La pestaña Redactar consta de los siguientes campos:

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

Idiomas

Puedes enviar un webhook a usuarios en múltiples mercados usando mensajes multilingüe. La traducción es compatible con el cuerpo de la solicitud y la URL del webhook.

Para localizar un webhook:

1. Crea las configuraciones regionales que desees admitir en tu espacio de trabajo.
2. En la pestaña Redactar, envuelve solo el texto que desees traducir con etiquetas de traducción. Por ejemplo, {% translation greeting %}Hello!{% endtranslation %}.
3. Selecciona Administrar idiomas, elige tus configuraciones regionales y después añade traducciones subiendo un CSV o usando la API de traducciones.
4. Selecciona Usuario multilingüe en el menú desplegable Vista previa como usuario para previsualizar cada configuración regional antes de enviar.

Importante

Envuelve solo los valores legibles por humanos en etiquetas de traducción. Nunca las claves JSON, los corchetes, las comas u otra estructura. Los traductores pueden alterar o eliminar caracteres especiales, lo que puede producir un cuerpo de solicitud con formato incorrecto que tu endpoint rechace.

Para un cuerpo de solicitud construido con pares clave-valor JSON, etiqueta solo el valor:

1
2
3

{
  "message_body": "{% translation order_ready %}Your order just arrived!{% endtranslation %}"
}

Localizar la URL

Si tu endpoint difiere según el mercado, puedes envolver parte de la URL en etiquetas de traducción. Mantén el protocolo (https://) fuera de las etiquetas y no incluyas parámetros de consulta dentro de ellas. Para más detalles, consulta Localizar URLs.

Plantillas de webhook

Las plantillas de webhook admiten traducciones guardadas, por lo que puedes localizar una plantilla una vez y reutilizarla en Campaigns y pasos en Canvas. Necesitas el permiso Edit Webhook Templates para añadir configuraciones regionales y traducciones a una plantilla. Consulta Plantillas de webhook.

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 debe 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 comunican a través de los puertos estándar 80 (HTTP) y 443 (HTTPS).

Usar 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 de información específica 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, utilizará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 introducir tu par clave-valor, el creador configurará tu solicitud con sintaxis JSON, y una vista previa de tu solicitud JSON se llenará automáticamente.

Puedes personalizar tus pares clave-valor usando Liquid, como incluir 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 para escribir una solicitud para un endpoint que espera un cuerpo en cualquier formato. Por ejemplo, podrías usarlo para escribir una solicitud para un endpoint que espera que tu solicitud esté en formato XML.

Tanto la personalización como las etiquetas de traducción 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 formatearse como una cadena codificada como 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 Compose 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 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 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 comunes son application/json o application/x-www-form-urlencoded.

Los encabezados de autorización deben utilizar 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ía un mensaje de prueba

Antes de que tu campaña entre en funcionamiento, 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 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 las reglas de limitación de frecuencia.

Elige los usuarios a los que dirigirte

A continuación, debes segmentar a los usuarios eligiendo segmentos o filtros para reducir 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 del tamaño aproximado de la población 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 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, incluidas las pruebas multivariante y Optimizar con BrazeAI^TM, consulta Construye tu Canvas.

Paso 6: Revisar e implementar

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 reintento y tiempos de espera

Los webhooks dependen de que los servidores de Braze realicen solicitudes a un endpoint externo, y ocasionalmente pueden producirse errores. 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:

• Comprueba si tu webhook tiene 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, que incluye detalles como la marca de tiempo del error, el nombre de la aplicación y los detalles del 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. Normalmente proporcionan una explicación de los códigos de error que usa el endpoint y las causas habituales de cada uno.

Códigos de respuesta y lógica de reintento

Cuando se envía la solicitud de webhook, el servidor receptor devuelve un código de respuesta que indica lo que ocurrió con la solicitud. La siguiente tabla resume las diferentes respuestas que puede enviar el servidor, cómo afectan al 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 de 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 conectarse con tu endpoint, los reintentos pueden continuar durante un máximo de 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 webhooks parecen faltar en el análisis, abre el registro de actividad de mensajes de la Campaign o del 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 consultar la tabla completa de respuestas, consulta Códigos de respuesta y lógica de reintento.

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

Las respuestas 403 Forbidden significan que tu endpoint recibió la solicitud pero la rechazó. Las causas habituales incluyen autenticación no vá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 salientes de Braze.

Si las solicitudes de webhook devuelven 403 de forma constante y tus encabezados de autenticación son correctos, añade las IP de Braze de tu clúster a la lista de permitidas en el servidor que recibe el webhook. Consulta Lista de IP permitidas. Las solicitudes de contenido conectado utilizan las mismas IP salientes; consulta Lista de IP permitidas de contenido conectado.

Para otros pasos de solución de problemas con errores 4XX, consulta Solución de problemas con 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 autenticarse con tu endpoint. En su lugar, configura la autenticación usando los 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 enumere 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 utilizan la misma URL y método HTTP, o contacta con el 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 webhooks, consulta Solución de problemas con 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 error a través de correos electrónicos automatizados y registro adicional en Braze Currents.

Lista 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 la lista de IP permitidas, puedes verificar que las solicitudes de webhook provienen de Braze, lo que añade una capa de seguridad.

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

Importante

Si estás haciendo un webhook de Braze a Braze y utilizas la lista de permitidas, debes añadir 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 consultar los pasos, límites y permisos, ve a Eliminar usuarios.

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