Saltar al contenido principal
Los webhooks de Journey envían solicitudes HTTP desde un paso de Journey a tus servidores o cualquier endpoint públicamente accesible. Configuras el método HTTP, la URL, los encabezados y el contenido del cuerpo. Las solicitudes pueden personalizarse con datos específicos del usuario mediante la sintaxis Liquid, lo que te permite sincronizar eventos de Journey con CRM, plataformas de análisis o backends personalizados en tiempo real.

​
Requisitos

  • Contacta al equipo de ventas de OneSignal para obtener acceso.
  • La URL o dirección IP debe ser válida y accesible mediante HTTP o HTTPS.
  • Los endpoints deben ser públicamente enrutables — no detrás de un firewall ni en localhost.
  • Los dominios deben tener un dominio de nivel superior válido (.com, .org, .net, etc.).
Los webhooks de Journey no pueden llamar a las API de OneSignal. Están diseñados únicamente para enviar datos a sistemas externos.

​
Configuración

Una vez que tu Journey está creado, sigue estos pasos:
  1. Navega a Datos > Webhooks en el panel de OneSignal.
  2. Haz clic para crear un nuevo webhook.
  3. Define lo siguiente:
    • Método HTTP (generalmente POST)
    • URL de destino
    • Encabezados personalizados (por ejemplo, tokens de autenticación)
    • Contenido del cuerpo (texto plano o JSON, opcionalmente usando Liquid)
Formulario de configuración del webhook con campos de método HTTP, URL, encabezados y cuerpo

​
Encabezados no permitidos

No puedes establecer los siguientes encabezados:
  • content-length
  • referer
  • metadata-flavor
  • x-google-metadata-request
  • host
  • Cualquier encabezado que comience con x-onesignal

​
Probar webhooks

También puedes probar tu endpoint manualmente usando una herramienta como curl: 
curl -X POST https://yourserver.com/webhook \
  -H "Content-Type: application/json" \
  -d '{ "user_id": "abc123" }'
Útil para validar que tu endpoint sea accesible y funcione antes de agregarlo a un Journey.

​
Personalización

Todos los campos de webhook soportan sintaxis Liquid, lo que te permite insertar dinámicamente datos de usuario y suscripción en la solicitud. Consulta Personalización de mensajes para la lista completa de propiedades disponibles.

​
Referencia de datos de usuario

Las siguientes propiedades del objeto user están disponibles en campos de webhook mediante sintaxis Liquid:
PropiedadTipoUso¿Disponible en prueba?
OneSignal IDString{{ user.onesignal_id }}✅
External IDString{{ user.external_id }}✅
TagsObject{{ user.tags.your_tag_key_here }}❌
LanguageString{{ user.language }}✅
Las etiquetas no están disponibles al probar webhooks fuera de un Journey activo. Usa Suscripciones de prueba para validar el comportamiento antes de activarlo.

​
Agregar un webhook a un Journey

  1. Después de crear y probar tu webhook, abre tu Journey.
  2. Agrega un paso de Webhook donde sea necesario.
  3. Selecciona el webhook que configuraste anteriormente.
Cada vez que un usuario alcanza ese paso, el webhook se activa con sus datos personalizados.
Canvas de Journey con un paso de webhook conectado entre pasos de mensajes

​
Depuración y registros

​
Estadísticas del webhook

Ve a la pestaña Estadísticas del webhook para ver el rendimiento de tu webhook. Esto incluye:
  • Total de eventos enviados
  • Tendencias de tiempo de respuesta
  • Distribución de código de estado
Pestaña de estadísticas del webhook con recuento de eventos, tendencias de tiempo de respuesta y distribución de códigos de estado

​
Pestaña de registros

Para información más detallada, la pestaña de Registros muestra:
  • Datos de solicitud/respuesta recientes
  • Códigos de estado y mensajes de error
  • Encabezados y cargas útiles (cuando aplique)
Pestaña de registros del webhook con solicitudes recientes, códigos de estado y cargas útiles

​
Lógica de reintento y comportamiento de deshabilitación

OneSignal reintenta solicitudes de webhook fallidas para errores recuperables (por ejemplo, 429 Too Many Requests). Los reintentos ocurren con retrasos crecientes. Si los reintentos fallan repetidamente, el webhook se marca como permanentemente fallido y no se hacen más intentos.

​
Deshabilitación automática

Si un webhook falla de forma consistente, OneSignal lo deshabilita para prevenir más problemas. Los administradores reciben alertas por correo electrónico y un banner en el panel antes y después de que se deshabilite un webhook. Identifica la causa raíz y prueba el webhook antes de volver a habilitarlo. Tu endpoint debe ser capaz de manejar el volumen de eventos que produce tu Journey. Revisa el volumen de envío de mensajes de tu aplicación para estimar el rendimiento que necesita tu API.

​
Guía de rendimiento

  • Los endpoints lentos o sobrecargados (especialmente los que devuelven respuestas 429) pueden activar la deshabilitación automática.
  • Registra eventos rápidamente y difiere el procesamiento adicional para evitar tiempos de espera.
  • El volumen escala con la actividad del usuario — asegúrate de que tu endpoint pueda manejar el rendimiento máximo.
  • Usa el valor event.id (disponible como encabezado o en el cuerpo) para deduplicar eventos entrantes.

​
Mejores prácticas de confiabilidad

  • Enruta primero a través de tu propio servidor, no directamente a servicios de terceros. Esto te da control sobre el registro, la autenticación, la limitación y la gestión de colas. Los servicios de terceros pueden limitar o bloquear solicitudes durante picos de volumen, y OneSignal no gestiona esos límites.
  • Planifica para ráfagas. La ejecución del webhook ocurre inmediatamente cuando los usuarios alcanzan el paso. Si muchos usuarios llegan a un paso de webhook a la vez, OneSignal envía una ráfaga de solicitudes HTTP sin limitación de velocidad. Considera construir una capa de API ligera o proxy de cola que pueda ingerir webhooks de manera confiable, aplicar límites de velocidad o procesamiento por lotes, y enrutar solicitudes a tus servicios de terceros de manera apropiada.
  • Revisa los límites de API de terceros. Las herramientas populares como Slack, Twilio y Segment ofrecen API HTTP públicas, pero tienen sus propios límites de velocidad, requisitos de autenticación y manejo de errores. Consulta su documentación antes de conectarte directamente.

​
Proteger tu webhook

Para verificar que las solicitudes provienen de OneSignal y no han sido alteradas:
  • Firma HMAC: Incluye un secreto compartido en la configuración del webhook. OneSignal firma cada solicitud con un encabezado HMAC que tu servidor puede validar antes de procesar la carga útil.
  • Token de autenticación personalizado: Agrega un encabezado de autorización personalizado (por ejemplo, Authorization: Bearer TU_TOKEN_SECRETO) y verifícalo del lado del servidor antes de aceptar la solicitud.

​
Preguntas frecuentes

​
¿Puedo usar webhooks para llamar a las API de OneSignal?

No. Los webhooks de Journey están diseñados únicamente para enviar datos a sistemas externos. No pueden llamar a las API de OneSignal. Para actualizar datos de OneSignal basándote en eventos de Journey, enruta el webhook a través de tu propio servidor y haz que tu servidor llame a la API de OneSignal.

​
¿Por qué mi webhook fue deshabilitado automáticamente?

OneSignal deshabilita los webhooks que fallan de forma consistente para prevenir más problemas. Revisa la pestaña Registros para ver los detalles del error (códigos de estado, cuerpos de respuesta), corrige la causa raíz y prueba el webhook antes de volver a habilitarlo. Las causas comunes incluyen tiempo de inactividad del endpoint, errores de autenticación y limitación de velocidad.

​
¿Cómo deduplico eventos de webhook?

Usa el valor event.id (disponible como encabezado o en el cuerpo de la solicitud) para identificar eventos únicos. Almacena los ID de eventos procesados en tu servidor y omite cualquier duplicado. Esto es especialmente importante si los reintentos entregan el mismo evento más de una vez.

​
¿OneSignal limita la velocidad de las solicitudes de webhook?

No. OneSignal envía solicitudes de webhook inmediatamente cuando los usuarios alcanzan el paso, sin limitación de velocidad. Si muchos usuarios llegan a un paso de webhook a la vez, tu endpoint recibe una ráfaga de solicitudes. Construye tu endpoint para manejar el volumen máximo, o usa un proxy de cola para almacenar en búfer y procesar por lotes las solicitudes.

​
¿Puedo probar webhooks sin lanzar un Journey?

Sí. Usa el botón Probar en la configuración del webhook para enviar una solicitud de muestra. Ten en cuenta que las etiquetas no están disponibles en las solicitudes de prueba — usa suscripciones de prueba en un Journey activo para una validación completa.

​
Páginas relacionadas

Descripción general de Journeys

Introducción a los Journeys y cómo funcionan los flujos multicanal.

Acciones de Journey

Agrega pasos de espera, lógica de ramificación, ventanas de tiempo y rutas divididas.

Sintaxis Liquid

Referencia completa para plantillas Liquid en mensajes y webhooks de OneSignal.

Personalización de mensajes

Descripción general de todos los métodos de personalización incluyendo etiquetas, Liquid y contenido dinámico.