Saltar al contenido principal

​
Descripción general

Los Webhooks Web Push te permiten recibir notificaciones HTTP POST en tiempo real cada vez que los usuarios interactúan con tus notificaciones push. Cuando una notificación se muestra, se hace clic o se descarta, OneSignal automáticamente envía los datos de la notificación y cualquier parámetro personalizado a tu URL de webhook especificada.
Para webhooks de Journey, ver nuestra página Webhooks de Journey.
Beneficios clave:
  • Rastrea el engagement de notificaciones en tiempo real
  • Activa flujos de trabajo automatizados basados en interacciones del usuario
  • Sincroniza datos de notificaciones con tu plataforma de analytics
  • Implementa lógica de negocio personalizada para eventos de notificaciones

​
Soporte de navegadores

NavegadorSoporte de plataformaEventos de webhook disponibles
ChromemacOS, Windows, AndroidTodos los eventos (display, click, dismiss)
FirefoxmacOS, Windows, AndroidEventos display y click
SafariNo soportadoNinguno

​
Eventos de webhook disponibles

​
notification.willDisplay

Se activa inmediatamente después de que aparece una notificación en la pantalla del usuario. Casos de uso: Rastrea tasas de entrega, registra datos de impresión, activa campañas de seguimiento

​
notification.clicked

Se activa cuando un usuario hace clic en el cuerpo de la notificación o cualquier botón de acción. Casos de uso: Rastrea tasas de engagement, activa eventos de conversión, redirige usuarios a contenido específico

​
notification.dismissed

Se activa cuando un usuario descarta activamente una notificación o cuando expira automáticamente. Soporte de navegador: Solo Chrome Casos de uso: Rastrea tasas de descarte, optimiza el tiempo de notificaciones, prueba A/B de contenido de notificaciones Importante: Hacer clic en el cuerpo de la notificación o botones de acción NO activa el webhook dismissed.

​
Métodos de configuración

  • Configuración de Dashboard (Recomendado para la mayoría de usuarios)
  • Integración con código personalizado
1
Navega a Settings > Web en tu dashboard de OneSignal
2
Habilita el toggle “Enable webhooks”
3
Ingresa tus URLs de webhook para cada evento que quieres rastrear

Habilita webhooks en la configuración de tu dashboard de OneSignal

Asegúrate de que tus URLs de webhook sean HTTPS (requerido por las políticas de seguridad de Chrome).

​
Configuración CORS

La configuración cors determina qué encabezados y datos recibe tu endpoint de webhook:
  • cors: false (Recomendado): Configuración más simple, no se necesita configuración CORS en tu servidor
  • cors: true: Proporciona encabezados adicionales pero requiere soporte CORS en tu servidor
Cuándo usar cors: true:
  • Necesitas el encabezado Content-Type: application/json
  • Quieres el encabezado X-OneSignal-Event para identificación de eventos más fácil
  • Tu servidor ya soporta CORS para solicitudes no simples

​
Formato de solicitud de webhook

​
Solicitud estándar (cors: false)

Tu endpoint de webhook recibe una solicitud POST con esta estructura de payload: 
{
  "event": "notification.clicked",
  "notificationId": "ed46884e-0e3f-4373-9e11-e28f27746d3d",
  "heading": "Tu título de notificación",
  "content": "Tu mensaje de notificación",
  "additionalData": {
    "userId": "12345",
    "campaignId": "summer-sale",
    "customField": "customValue"
  },
  "actionId": "buy-now-button",
  "url": "https://yoursite.com/product/123"
}

​
Solicitud mejorada (cors: true)

Mismo payload que arriba, más estos encabezados adicionales: 
Content-Type: application/json
X-OneSignal-Event: notification.clicked

​
Referencia de campos del payload

CampoTipoDescripciónSiempre presente
eventstringTipo de evento que activó el webhook✅
notificationIdstringIdentificador único de notificación OneSignal✅
headingstringTítulo de la notificaciónSolo si se proporciona
contentstringCuerpo del mensaje de notificaciónSolo si se proporciona
additionalDataobjectDatos personalizados enviados con la notificaciónSolo si se proporciona
actionIdstringID del botón de acción clickeado (string vacío = clic en cuerpo de notificación)Solo eventos de clic
urlstringURL de lanzamiento para la notificaciónSolo si se proporciona
subscriptionIdstringID de usuario/suscripción de OneSignalSolo CORS habilitado

​
Mejores prácticas de implementación

​
Requisitos del endpoint de webhook

Seguridad:
  • Usa solo URLs HTTPS (las URLs HTTP serán bloqueadas por Chrome)
  • Implementa autenticación/validación adecuada para tus endpoints de webhook
  • Considera limitación de tasa para manejar notificaciones de alto volumen
Requisitos de respuesta:
  • Devuelve estado HTTP 200 para procesamiento exitoso
  • Responde dentro de 10 segundos para evitar timeouts
  • Maneja llamadas de webhook duplicadas con gracia (implementa idempotencia)

​
Manejo de errores

// Ejemplo de endpoint de webhook (Node.js/Express)
app.post('/webhook/notification', (req, res) => {
  try {
    const { event, notificationId, additionalData } = req.body;

    // Valida campos requeridos
    if (!event || !notificationId) {
      return res.status(400).json({ error: 'Faltan campos requeridos' });
    }

    // Procesa los datos del webhook
    processNotificationEvent(req.body);

    // Siempre responde con 200 OK
    res.status(200).json({ success: true });
  } catch (error) {
    console.error('Error de procesamiento de webhook:', error);
    res.status(500).json({ error: 'Error interno del servidor' });
  }
});

​
Problemas comunes y soluciones

​
Los webhooks no se activan

Causas posibles:
  • Código de webhook no presente en todas las páginas con inicialización OneSignal
  • El usuario no ha visitado una página con código de webhook después de agregarlo
  • Requisito HTTPS no cumplido
  • Servidor devolviendo códigos de estado no-200
Solución: Asegúrate de que la configuración de webhook esté incluida en tu código init de OneSignal en todas las páginas donde las notificaciones están activas.

​
Datos faltantes en webhooks

Causa: Los webhooks solo rastrean eventos para usuarios que visitan páginas con la configuración de webhook activa. Solución: Despliega código de webhook en todas las páginas con OneSignal, no solo páginas de destino específicas.

​
Llamadas de webhook duplicadas

Causa: Problemas de red o comportamiento del navegador pueden causar solicitudes duplicadas. Solución: Implementa idempotencia usando el campo notificationId para deduplicar eventos.

​
Limitaciones de webhook

  • Una URL de webhook por evento: No puedes establecer múltiples URLs de webhook para el mismo tipo de evento
  • Solo HTTPS: Las URLs HTTP no funcionarán debido a restricciones de seguridad del navegador
  • Rastreo de descarte solo Chrome: El evento notification.dismissed solo funciona en Chrome
  • Dependencia de página: Los usuarios deben visitar páginas con código de webhook activo para que el rastreo funcione

​
Probar tus webhooks

  1. Envía una notificación de prueba a través de tu dashboard de OneSignal
  2. Monitorea tu endpoint de webhook para solicitudes entrantes
  3. Verifica la estructura del payload que coincida con tus expectativas
  4. Prueba diferentes escenarios:
    • Visualización de notificación
    • Clic en cuerpo de notificación
    • Clic en botones de acción (si están configurados)
    • Descarte de notificaciones (solo Chrome)

​
Siguientes pasos

Después de configurar webhooks, considera:
  • Integración de Analytics: Reenvía datos de webhook a tu plataforma de analytics
  • Segmentación de usuarios: Usa eventos de webhook para crear segmentos de usuarios basados en engagement
  • Flujos de trabajo automatizados: Activa campañas de email o notificaciones de app basadas en interacciones de notificaciones push
  • Pruebas A/B: Usa datos de webhook para medir la efectividad de diferentes estrategias de notificación