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 sabes si tu mensaje debe enviarse mediante una campaña o un Canvas? Las campañas son mejores para campañas de mensajería sencillas y dirigidas, mientras que los Canvas son mejores para recorridos de usuario de varios pasos.

• campaign
• canvas

Pasos:

1. Ve a Mensajería > Campañas y selecciona Crear campaña.
2. Selecciona Webhook o, para campañas dirigidas a varios canales, selecciona Multicanal.
3. Ponle 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 crear informes a partir de ellas. Por ejemplo, cuando utilices el Generador de informes, puedes filtrar por etiquetas concretas.
6. Añade y nombra tantas variantes como necesites para tu campaña. Puedes elegir distintas plantillas de webhook para cada una de las variantes que añadas. 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. Después podrás elegir Copiar de la 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 crear un webhook nuevo, 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 tiene los siguientes campos:

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

Idiomas

Puedes enviar un mismo webhook a usuarios de varios mercados usando mensajes multilingües. La traducción es compatible con el cuerpo de la solicitud y con la URL del webhook.

Para localizar un webhook:

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

Importante

Envuelve en etiquetas de traducción solo los valores legibles por personas. Nunca envuelvas claves JSON, corchetes, comas ni ningún otro elemento de la estructura. Los traductores pueden alterar o eliminar caracteres especiales, lo que puede generar un cuerpo de solicitud mal formado que tu endpoint rechace.

Para un cuerpo de solicitud creado 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 varía según el mercado, puedes envolver parte de la URL en etiquetas de traducción. Deja el protocolo (https://) fuera de las etiquetas y no incluyas parámetros de consulta dentro de ellas. Para más información, consulta Localizar URL.

Plantillas de webhook

Las plantillas de webhook admiten traducciones guardadas, así que puedes localizar una plantilla una sola vez y reutilizarla en Campaigns y pasos en Canvas. Necesitas el permiso Editar plantillas de webhook 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 al que enviarás la información que capturas en el webhook.

Si quieres enviar información a un proveedor, este debería indicar esta URL en su documentación de la API. Si vas a enviar información a tus propios sistemas, consulta con tu equipo de desarrollo o ingeniería para confirmar que usas la URL correcta.

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

Uso de Liquid

Puedes personalizar las URL de tu webhook usando Liquid. En ocasiones, algunos endpoints pueden requerir que identifiques a un usuario o que proporciones información específica del usuario como parte de la URL. Cuando uses Liquid, asegúrate de incluir un valor predeterminado para cada dato específico del usuario que uses en la URL.

Método HTTP

El método HTTP que debes usar depende del endpoint al que envíes la 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 con 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 esta opción 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!. Cuando hayas introducido tu par clave-valor, el creador configurará tu solicitud con sintaxis JSON y se mostrará automáticamente una vista previa de tu solicitud JSON.

Puedes personalizar tus pares clave-valor con Liquid, por ejemplo incluyendo en tu solicitud cualquier atributo de usuario, atributo personalizado o propiedad de evento. 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 flexibilidad para escribir una solicitud para un endpoint que espera un cuerpo en cualquier formato. Por ejemplo, puedes usarla 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 tener el formato de una cadena codificada como URL. Por ejemplo:

1

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

Paso 3: Configura los ajustes adicionales

Usar una credencial guardada (opcional)

Usa una credencial guardada para autenticar un webhook sin tener que introducir su contraseña o token en el mensaje. Puedes reutilizar credenciales de autenticación básica y de autenticación por token desde Configuración > Gestión de credenciales en campañas webhook, pasos en Canvas y plantillas de webhook.

Cada credencial pertenece a un único espacio de trabajo. Crea una credencial en cada espacio de trabajo donde la necesites, incluidos los espacios de trabajo separados de desarrollo, staging y producción.

Para seleccionar una credencial existente, necesitas el permiso “Manage App Group” o el permiso de edición correspondiente: “Edit Campaigns”, “Edit Canvases” o “Edit Webhook Templates”. Para crear, editar o eliminar credenciales, necesitas el permiso “Manage App Group”. Si es necesario, pide a tu administrador del espacio de trabajo que te lo conceda.

1. En la pestaña Redactar, introduce una URL de webhook HTTPS con un nombre de host fijo, como https://api.example.com/events. Puedes usar Liquid en la ruta o en los parámetros de consulta, pero el nombre de host debe ser estático para poder seleccionar una credencial.
2. En Credencial, selecciona una credencial guardada. La lista muestra las credenciales cuyo dominio permitido coincide con el nombre de host de la URL, incluidas las credenciales que permiten un dominio principal.
3. Si tienes permiso para crear credenciales, selecciona Añadir credencial en el selector para crear una. Selecciona Autenticación básica o Autenticación por token, introduce un nombre de credencial único y los datos de autenticación, y selecciona Añadir credencial. El dominio permitido se rellena a partir del nombre de host del webhook y no se puede cambiar en este formulario.
4. Confirma la credencial seleccionada antes de guardar o enviar un webhook de prueba.

Si tu nombre de host procede de Liquid o de un Content Block, mantén la autenticación en los encabezados de solicitud. Para usar una credencial guardada, cambia la URL a un nombre de host fijo y mantén los valores dinámicos en la ruta o en los parámetros de consulta.

Ambos tipos de credencial requieren un dominio permitido para usarse con webhooks. Una credencial de autenticación básica sin dominio puede seguir usándose para el contenido conectado, pero no está disponible en el selector de webhooks. Consulta la columna Disponible en de la página Gestión de credenciales para confirmar si una credencial admite webhooks. Para ver ejemplos de configuración y de dominios, consulta Tipos de autenticación.

Advertencia

El dominio permitido de una credencial incluye todos sus subdominios. Usa el nombre de host más específico que controle tu organización. Un dominio principal compartido puede permitir que el subdominio de otra organización reciba tu credencial. Consulta Elegir un dominio permitido.

Braze aplica la autenticación guardada al enviar la solicitud. La autenticación básica proporciona el encabezado Authorization. La autenticación por token proporciona los encabezados guardados en la credencial. Si introduces manualmente un encabezado con el mismo nombre, prevalece el valor de la credencial guardada. Los nombres de los encabezados no distinguen entre mayúsculas y minúsculas.

Si cambias la URL de forma que la credencial seleccionada ya no coincida, el creador borra la selección. Vuelve a seleccionar una credencial que coincida antes de guardar. Braze también valida la credencial y la URL de destino renderizada en el momento del envío. Una credencial no válida o un destino no permitido impide que se envíe el webhook.

Para actualizar o eliminar una credencial guardada, consulta Gestionar credenciales guardadas.

Vista previa de credenciales guardadas

La vista previa del webhook muestra la URL renderizada, el cuerpo y los encabezados de solicitud introducidos manualmente. Omite la referencia a la credencial seleccionada y los encabezados de autenticación que proporciona esa credencial, en lugar de mostrar valores enmascarados. Braze aplica la credencial guardada al enviar un webhook de prueba o en vivo.

En el creador, los usuarios sin el permiso “Manage App Group” o el permiso de edición correspondiente ven Oculto en el selector Credencial deshabilitado cuando hay una credencial seleccionada. No pueden ver ni cambiar la selección.

Encabezados de solicitud (opcional)

Algunos 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 Content-Type (que describen qué tipo de datos se esperan en el cuerpo, como XML o JSON) y los encabezados 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 las CDN) transforma las mayúsculas y minúsculas de los encabezados, esto no afectará a su procesamiento: Content-Type, content-type y CONTENT-TYPE se tratan exactamente igual.

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

Los encabezados de autorización deben usar la clave Authorization. Los valores habituales son Bearer {{YOUR_TOKEN}} o Basic {{YOUR_TOKEN}} , donde YOUR_TOKEN son las credenciales que te proporciona tu proveedor o sistema.

Paso 4: Envía una prueba de tu mensaje

Antes de poner en marcha tu campaña, Braze recomienda que pruebes el webhook para asegurarte de que la solicitud tiene el formato correcto. Si seleccionaste una credencial guardada, el envío de prueba la utiliza para autenticar la solicitud.

Para ello, 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 su 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 se realiza correctamente, 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: Crea el resto de tu campaña o Canvas

• campaign
• canvas

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

Elige el calendario de entrega o el desencadenante

Los webhooks pueden entregarse según una hora programada, 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 los controles de entrega, como permitir que los usuarios vuelvan a ser elegibles para recibir la campaña o activar 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 acotar tu audiencia. En este paso, seleccionas la audiencia más amplia a partir de tus segmentos y, si quieres, acotas aún más ese segmento con nuestros filtros. Recibirás automáticamente una vista previa del aspecto 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, los eventos de conversión, después de recibir una campaña. Tienes la opción de permitir un plazo de hasta 30 días durante el 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 más información sobre cómo crear el resto de tu Canvas, incluidas las pruebas multivariante y Optimizar con BrazeAI^TM, consulta Crear tu Canvas.

Paso 6: Revisar e implementar

Cuando termines de crear tu campaña o Canvas, revisa sus detalles, pruébalo y, después, ¡envíalo!

Lo 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 en ocasiones 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 Campaign de webhook:

• Prueba tu webhook para detectar 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 detalles sobre el error.

Si el mensaje de error no es lo bastante claro sobre el origen del error, consulta la documentación del endpoint de la API que estás utilizando. Normalmente incluye una explicación de los códigos de error que utiliza el endpoint y de sus causas habituales.

Códigos de respuesta y lógica de reintentos

Cuando se envía la solicitud de webhook, el servidor receptor devuelve un código de respuesta que indica qué ha ocurrido con la solicitud. La siguiente tabla resume las distintas respuestas que puede enviar el servidor, cómo afectan al análisis de la Campaign y si, en caso de error, Braze intentará volver a entregar la Campaign:

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 contactar con tu endpoint, los reintentos pueden continuar durante un máximo de 24 horas.

Cada solicitud de webhook dispone de 120 segundos antes de que se agote el tiempo de espera.

Los encabezados de respuesta Retry-After y de límite de velocidad pueden influir en 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 parece que faltan envíos de webhook en los análisis, abre el Registro de actividad de mensajes de la Campaign o del paso en Canvas. Braze solo reintenta determinadas respuestas (por ejemplo, 408, 429 y 5XX); la mayoría de los demás errores de cliente 4XX, incluido 401 Unauthorized, no se reintentan. Para ver la tabla completa de respuestas, consulta Códigos de respuesta y lógica de reintentos.

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 una 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 sistemática 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 para contenido conectado.

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

Autenticación y credenciales de contenido conectado

Selecciona una credencial en el creador de webhooks para autenticar la solicitud saliente. En esta página, consulta Usar una credencial guardada.

Las opciones de Liquid :basic_auth y :auth_credentials solo autentican la llamada {% connected_content %} en la que aparecen. No seleccionan una credencial para la solicitud principal del webhook. Para obtener un token o un secreto en el momento del envío, puedes colocar una etiqueta {% connected_content %} en un campo del encabezado o del cuerpo para que Liquid la resuelva antes de enviar el webhook.

Plantillas de webhook guardadas y uso en Campaigns

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

Solución de problemas y detalles adicionales sobre errores

Para obtener explicaciones detalladas, pasos de solución de problemas e indicaciones para resolver errores específicos de webhooks, consulta Solución de problemas de solicitudes de webhook y contenido conectado. Allí 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 envía notificaciones de error mediante correos electrónicos automatizados y registros adicionales 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 proceden de Braze, lo que añade 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 incluido en la lista de permitidas.

Importante

Si estás creando un webhook de Braze a Braze y utilizas la lista de permitidas, debes añadir a la lista todas las IP siguientes, 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 25 millones de perfiles), incluye un periodo de cancelación de 7 días y no consume los límites de velocidad compartidos de la REST API. Para conocer los pasos, los límites y los 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 Campaign de webhook.