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.

Paso 1: Elige dónde crear tu mensaje

¿No tienes claro si tu mensaje debe enviarse mediante una campaña o un Canvas? Las campañas son mejores para envíos de mensajería únicos y dirigidos, mientras que los Canvas son mejores para recorridos de usuario de varios pasos.

• campaign
• canvas

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 en la URL y en el cuerpo de la solicitud. Para internacionalizar tu mensaje, selecciona Add languages y completa los campos requeridos.

Te recomendamos seleccionar tus idiomas antes de escribir tu contenido para que puedas rellenar 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 rendericen. Para conocer las mejores prácticas sobre cómo crear mensajes de derecha a izquierda que se muestren con la mayor precisión posible, consulta Crear mensajes de derecha a izquierda.

URL del webhook

La URL del webhook, o URL HTTP, especifica tu punto de conexión. El punto de conexión 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 debe 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 comunican 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 puntos de conexión 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 punto de conexión 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 punto de conexión que espera un formato JSON. Solo puedes usar esto con un punto de conexión 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 compositor 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 punto de conexión que espera un cuerpo de cualquier formato. Por ejemplo, podrías usar esto para escribir una solicitud para un punto de conexión que espere que tu solicitud esté en formato XML.

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

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

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

Paso 3: Configura ajustes adicionales

Encabezados de solicitud (opcional)

Ciertos puntos de conexión pueden requerir que incluyas encabezados en tu solicitud. En la sección Compose del compositor, 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 se esperan en el cuerpo, como XML o JSON) y los encabezados de autorización que contienen tus credenciales con tu proveedor o sistema.

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ía un mensaje de prueba

Antes de poner tu campaña en marcha, Braze recomienda que pruebes el webhook para asegurarte de que la solicitud está formateada correctamente.

Para hacerlo, cambia a la pestaña Test 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

Paso 6: Revisa y despliega

Después de terminar de construir la última parte de tu campaña o Canvas, revisa sus detalles, pruébala y luego ¡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 punto de conexión externo, y ocasionalmente pueden ocurrir 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:

• 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, 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 punto de conexión de API que estás usando. Normalmente proporcionan una explicación de los códigos de error que utiliza el punto de conexión, 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 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 la campaña y si, en caso de errores, Braze intentará reenviar la campaña:

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.

Autenticación y credenciales de contenido conectado

La solicitud HTTP saliente del webhook no admite adjuntar credenciales de contenido conectado (:basic_auth o :auth_credentials) para autenticarse contra tu punto de conexión. Configura la autenticación usando Request headers 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 campañas

Braze no proporciona un informe integrado que liste cada campaña o paso de Canvas que haga referencia a una plantilla de webhook guardada determinada. Para auditar el uso, revisa los pasos de webhook que usen 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 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 no saludables y cómo Braze proporciona notificaciones de errores a través de correos electrónicos automatizados y registro adicional en Braze Currents.

Lista de IPs 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 IPs permitidas, puedes verificar que las solicitudes de webhook provienen de Braze, añadiendo una capa de seguridad.

Braze enviará webhooks desde las siguientes IPs. Las IPs listadas se añaden automática y dinámicamente a cualquier clave de API que haya sido habilitada para la lista de permitidos.

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