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.
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
| Navegador | Soporte de plataforma | Eventos de webhook disponibles |
|---|
| Chrome | macOS, Windows, Android | Todos los eventos (display, click, dismiss) |
| Firefox | macOS, Windows, Android | Eventos display y click |
| Safari | No soportado | Ninguno |
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
Navega a Settings > Web en tu dashboard de OneSignal
Habilita el toggle “Enable webhooks”
Ingresa tus URLs de webhook para cada evento que quieres rastrear
Agrega configuración de webhook a tu método OneSignal.init() existente:// Agrega a tu inicialización OneSignal existente - NO llames init dos veces
OneSignal.init({
// Tus otras configuraciones existentes aquí
webhooks: {
cors: false, // Recomendado: deja como false a menos que necesites encabezados personalizados
'notification.willDisplay': 'https://yoursite.com/webhook/display',
'notification.clicked': 'https://yoursite.com/webhook/click',
'notification.dismissed': 'https://yoursite.com/webhook/dismiss' // Solo Chrome
}
});
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 servidorcors: 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
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
| Campo | Tipo | Descripción | Siempre presente |
|---|
event | string | Tipo de evento que activó el webhook | ✅ |
notificationId | string | Identificador único de notificación OneSignal | ✅ |
heading | string | Título de la notificación | Solo si se proporciona |
content | string | Cuerpo del mensaje de notificación | Solo si se proporciona |
additionalData | object | Datos personalizados enviados con la notificación | Solo si se proporciona |
actionId | string | ID del botón de acción clickeado (string vacío = clic en cuerpo de notificación) | Solo eventos de clic |
url | string | URL de lanzamiento para la notificación | Solo si se proporciona |
subscriptionId | string | ID de usuario/suscripción de OneSignal | Solo 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
- Envía una notificación de prueba a través de tu dashboard de OneSignal
- Monitorea tu endpoint de webhook para solicitudes entrantes
- Verifica la estructura del payload que coincida con tus expectativas
- 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
