> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks web push

> Configura webhooks HTTP para recibir notificaciones en tiempo real cuando los usuarios muestran, hacen clic o descartan notificaciones web push. Guía completa con ejemplos para soporte de navegadores Chrome, Firefox y Safari.

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

<Warning>
  Para webhooks de Journey, ver nuestra página [Webhooks de Journey](./journeys-webhook).
</Warning>

**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

<Tabs>
  <Tab title="Configuración de Dashboard (Recomendado para la mayoría de usuarios)">
    <Steps>
      <Step>
        Navega a **Settings > Web** en tu dashboard de OneSignal
      </Step>

      <Step>
        Habilita el toggle "Enable webhooks"
      </Step>

      <Step>
        Ingresa tus URLs de webhook para cada evento que quieres rastrear
      </Step>
    </Steps>

    <Frame caption="Habilita webhooks en la configuración de tu dashboard de OneSignal">
      <img src="https://mintcdn.com/onesignal/Xl2NHJvxakrK4JbL/images/docs/eb3347d-image.png?fit=max&auto=format&n=Xl2NHJvxakrK4JbL&q=85&s=c6c064fe350777ee479e0a22eb8a7ea0" width="1822" height="656" data-path="images/docs/eb3347d-image.png" />
    </Frame>
  </Tab>

  <Tab title="Integración con código personalizado">
    Agrega configuración de webhook a tu método `OneSignal.init()` existente:

    ```javascript theme={null}
    // 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
      }
    });
    ```
  </Tab>
</Tabs>

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

## 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:

```json theme={null}
{
  "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:

```http theme={null}
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

```javascript theme={null}
// 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