Saltar al contenido principal
Con los Webhooks de Journey, puedes enviar solicitudes HTTP desde OneSignal Journeys a tus servidores—o cualquier servicio accesible por internet—en el momento preciso del ciclo de vida de un cliente. Configura el método HTTP, URL, encabezados y contenido del cuerpo para que coincidan con tus requisitos de integración. Las solicitudes pueden personalizarse dinámicamente con datos específicos del usuario, haciendo que los webhooks sean una forma poderosa de sincronizar tus Journeys con el resto de tu stack de marketing.

​
Requisitos

Antes de que los eventos puedan enviarse, asegúrate de:
  • Contactar a nuestro equipo de ventas para acceso.
  • La URL/dirección IP es válida y accesible a través de HTTP o HTTPS.
  • Los endpoints son enrutables públicamente (es decir, no detrás de un firewall o en localhost).
  • Los dominios deben tener un dominio de nivel superior válido (por ejemplo, .com, .org, .net).
  • Los webhooks de Journey no pueden usarse para llamar APIs de OneSignal.

​
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 (usualmente POST)
    • URL objetivo
    • Encabezados personalizados (por ejemplo, para autenticación)
    • Contenido del cuerpo (texto plano o JSON, opcionalmente usando Liquid)

Pantalla de configuración de webhook

​
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:
bash
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. Ver Personalización de mensajes para más detalles sobre las propiedades disponibles.

​
Referencia de datos de usuario

Las siguientes propiedades del objeto user están disponibles en campos de webhook a través de sintaxis liquid:
PropiedadTipoUso¿Disponible en prueba?
ID de OneSignalString{{ user.onesignal_id }}✅
ID externoString{{ user.external_id }}✅
EtiquetasObject{{ user.tags.your_tag_key_here }}❌
IdiomaString{{ 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 ponerlo en vivo.

​
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.

Un paso de webhook dentro de un journey

​
Depuración y registros

​
Estadísticas de webhook

Ve a la pestaña Estadísticas del webhook para ver cómo se está desempeñando tu webhook. Esto incluye:
  • Total de eventos enviados
  • Tendencias de tiempo de respuesta
  • Distribución de código de estado

La página de reportes de webhook

​
Pestaña de registros

Para información más granular, 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)

La página de registro de webhook

​
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 consistentemente, OneSignal lo deshabilita para prevenir más problemas. Los administradores reciben alertas por email y un banner en el panel antes y después de que un webhook se deshabilite. Si esto sucede, asegúrate de dedicar tiempo a solucionar problemas, arreglar y luego probar el webhook antes de volver a habilitarlo. Es importante que la API que ingiere un webhook pueda manejar el volumen de eventos que produce el envío de mensajes. Revisar el volumen de envíos de mensajes que produce tu app reflejará el rendimiento requerido de tu API.

​
Guía de rendimiento

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

​
Consejos para el éxito

  • Conecta webhooks a tus propios servidores primero, no directamente a servicios de terceros.
    • Si bien los webhooks de OneSignal pueden llamar a cualquier API pública, enrutar a través de tu propio servidor te da más control.
    • Es más fácil depurar, agregar registro, manejar autenticación y limitar o poner en cola solicitudes según sea necesario.
    • Los servicios de terceros pueden limitar la tasa o bloquear solicitudes si el volumen aumenta, y OneSignal no gestiona esos límites.
  • La ejecución del webhook ocurre inmediatamente cuando los usuarios alcanzan ese paso en el Journey.
    • Si muchos usuarios llegan a un paso de webhook a la vez, OneSignal enviará una ráfaga de solicitudes HTTP sin limitación de tasa.
    • Esto puede fácilmente abrumar servicios externos, activar límites de tasa o incurrir en cargos inesperados.
    • Considera construir una capa de API ligera o proxy de cola que pueda:
      • Ingerir webhooks de manera confiable
      • Aplicar límites de tasa o agrupamiento
      • Enrutar solicitudes a tus servicios de terceros con gracia
  • Usa APIs de terceros con cuidado:
    • La mayoría de las herramientas populares (por ejemplo, Slack, Twilio, Segment) ofrecen APIs HTTP públicas.
    • Revisa sus límites de tasa, requisitos de autenticación y estrategias de manejo de errores.
    • Busca ejemplos de código en sus documentos para ver cómo debería verse tu solicitud de webhook.

​
Asegurar tu webhook

Para asegurar que las solicitudes provienen de OneSignal y no han sido manipuladas:
  • Usa un encabezado de firma HMAC con un secreto compartido
  • Agrega un token de autenticación personalizado en el encabezado y veríficalo del lado del servidor

​
Enlaces relacionados: