> ## 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.
# Event Streams
> Envía datos de mensajes fuera de OneSignal en tiempo real al destino que elijas.
Event Streams te permite enviar datos de mensajes fuera de OneSignal en tiempo real al destino que elijas. Los event streams son una excelente manera de conectar OneSignal con otros productos dentro de tu ecosistema de marketing. Permiten a tu equipo activar mensajería correspondiente, mantener registros y mucho más.
Los tipos de eventos disponibles incluyen:
* Eventos de mensajes push (enviados, recibidos, clicados, fallidos, cancelación de suscripción)
* Eventos de email (enviados, abiertos, clicados, rebotados, cancelación de suscripción, etc.)
* Eventos de SMS (enviados, fallidos, cancelación de suscripción, etc.)
* Eventos de mensajes in-app (impresión, clicados, etc.)
* Eventos de Live Activity (enviados, entregados, entrega confirmada, fallidos, cancelación de suscripción, clicados)
## Casos de uso comunes
* **Centralizar datos de participación** — Transmite eventos a un CRM, CDP o almacén de datos para que la actividad multicanal (aperturas, clics, rebotes) esté en un solo lugar en lugar de distribuida entre herramientas desconectadas.
* **Análisis, informes y cumplimiento** — Almacena cada evento de mensaje en un almacén para análisis de tendencias, auditoría o conservación de registros normativos.
* **Monitorear la desvinculación** — Rastrea cancelaciones de suscripción, rebotes y descartes en tus propios sistemas para detectar riesgos de retención temprano.
* **Activar flujos de trabajo externos** — Dispara automatizaciones en otras herramientas cuando un usuario abre o hace clic en un mensaje (p. ej., actualizar una puntuación de leads, iniciar una secuencia de seguimiento).
* **Reemplazar sincronizaciones por lotes e integraciones adicionales** — Reacciona a eventos en tiempo real y conecta OneSignal directamente a tu destino, reduciendo herramientas intermediarias y costos de mantenimiento.
### Cómo poner en marcha a tu equipo técnico
Configurar Event Streams es un esfuerzo conjunto entre el propietario de marketing/producto (quien decide *qué* eventos importan y *a dónde* van) y el equipo de ingeniería (que construye el endpoint receptor y configura el stream). Esto es lo que involucra el lado de ingeniería:
1. **Decidir sobre un destino y alcance** — Acordar dónde deben llegar los eventos (tu propia API, un almacén de datos, un CDP, etc.), qué tipos de eventos transmitir (push, email, SMS, IAM, Live Activity) y una estimación del volumen de mensajes para que el endpoint tenga el tamaño adecuado.
2. **Configurar un endpoint HTTP** — Construir o configurar un endpoint públicamente accesible que acepte solicitudes POST. Debe registrar eventos rápidamente sin procesamiento pesado para mantener los tiempos de respuesta bajos. Consulta [Reintentos / Deshabilitación](#retries--disabling) para las expectativas de rendimiento y lo que sucede cuando el endpoint se queda atrás.
3. **Configurar el Event Stream en OneSignal** — En **Datos > Event Streams**, selecciona eventos, establece la URL y los encabezados de autenticación, y define el cuerpo JSON usando los campos de [Datos de Event Streams](./event-streams-data) con [sintaxis Liquid](./using-liquid-syntax).
4. **Probar de extremo a extremo** — Usa [webhook.site](https://webhook.site) para verificar la forma del payload y los encabezados antes de cambiar a tu endpoint de producción (consulta [Pruebas](#testing)).
***
## Configuración
Puedes configurar un nuevo event stream para tu aplicación de OneSignal bajo **Datos > Event Streams > Nuevo Event Stream**.
**Requisitos**
Los eventos no se pueden enviar a menos que se cumplan los siguientes requisitos:
* Una URL o dirección IP válida para un **endpoint HTTP(S)** públicamente accesible
* Las URLs y direcciones IP deben ser enrutables públicamente
* Los dominios deben incluir un dominio de nivel superior reconocido (por ejemplo, ".com", ".net")
### Selección de eventos
Asigna un nombre a tu Event Stream y haz clic en **Seleccionar Eventos**.
Esto abrirá la página de Selección de Eventos donde puedes seleccionar los eventos que deseas que activen tu event stream.
Cada evento cuenta hacia el volumen de eventos de mensajes de tu plan. Transmitir **cada** tipo de evento (especialmente `sent`) para una audiencia grande puede consumir tu asignación rápidamente — por ejemplo, un solo envío a 100,000 usuarios genera 100,000 eventos `sent` por sí solo.
Para gestionar el volumen:
* **Selecciona solo los tipos de eventos que necesitas** — p. ej., `received` y `clicked` pueden ser suficientes si no necesitas seguimiento a nivel de envío.
* **Usa [filtros de event stream](#event-stream-filters)** para limitar los eventos a mensajes o plantillas específicas en lugar de transmitir todo el tráfico.
#### Filtros de event stream
Puedes refinar opcionalmente los eventos especificando los identificadores de uno o más mensajes o plantillas, lo que te permite recibir solo eventos relacionados con mensajes específicos.
Los identificadores de plantilla se pueden copiar navegando a **Mensajes > Plantillas**. Junto a la plantilla que deseas rastrear, selecciona **Opciones > Copiar ID de Plantilla** y pégalo en los filtros del Event Stream.
### Configurar el Event Stream
Selecciona el método HTTP, la URL y agrega encabezados para el event stream. Aquí es donde debe configurarse la autenticación para asegurar la comunicación segura entre OneSignal y tus sistemas.
La URI y los encabezados pueden contener sintaxis liquid que provendrá tanto de las propiedades del usuario como de las propiedades del event stream.
#### Encabezados de autenticación
Puedes agregar encabezados de autenticación para validar que las solicitudes a tu endpoint son genuinamente de OneSignal. Los métodos de autenticación comunes incluyen:
* **Encabezado de autorización**: Agrega un encabezado `Authorization`, donde `YOUR_TOKEN` es proporcionado por tu sistema o un tercero como:
* `Basic {{YOUR_TOKEN}}`
* `Bearer {{YOUR_TOKEN}}`
* `ApiKey {{YOUR_API_KEY}}`
* **Encabezados personalizados**: También puedes agregar encabezados personalizados como:
* `X-API-Key: {{YOUR_API_KEY}}`
*Nota: OneSignal no proporciona servicios de encriptación*
#### Probando tu configuración
Si buscas una forma fácil de probar, usa [webhook.site](https://webhook.site). Encuentra "Your unique URL" en el centro de la página. Copia esa URL y úsala en el campo URL de tu configuración de event stream.
#### Encabezados no permitidos
Los siguientes encabezados están restringidos y no se pueden establecer.
* `content-length`
* `referer`
* `metadata-flavor`
* `x-google-metadata-request`
* `host`
* `x-onesignal*`
### Cuerpo
El cuerpo de un event stream será JSON. El JSON del cuerpo puede definirse como pares clave/valor individuales o como un bloque de código editable. Para cambiar el método de entrada, usa el primer menú desplegable bajo el encabezado del cuerpo y selecciona el cuerpo personalizado.
A la derecha, puedes ver una solicitud cURL de ejemplo construida a partir de lo que se ha ingresado durante la configuración del event stream
### Personalización
Puedes personalizar todos los campos en tu Event Stream con [Datos de Event Streams](./event-streams-data) predefinidos. Estos datos se pueden agregar usando [Sintaxis Liquid](./using-liquid-syntax). Esto te da la flexibilidad de usar event streams para casi cualquier caso de uso.
Consulta [Datos de Event Streams](./event-streams-data) para una lista de todos los datos de eventos, mensajes y usuarios disponibles para personalización.
#### Ejemplo de cuerpo
Selecciona el "Cuerpo Personalizado" en el menú desplegable:
```json JSON theme={null}
{
"Event Data": {
"event.kind": "{{ event.kind }}",
"event.id": "{{ event.id }}",
"event.timestamp": "{{ event.timestamp }}",
"event.datetime": "{{ event.datetime }}",
"event.app_id": "{{ event.app_id }}",
"event.subscription_device_type": "{{ event.subscription_device_type }}",
"event.subscription_id": "{{ event.subscription_id }}",
"event.onesignal_id": "{{ event.onesignal_id }}",
"event.external_id": "{{ event.external_id }}",
"event.data.page_name": "{{ event.data.page_name}}",
"event.data.page_id": "{{ event.data.page_id}}",
"event.data.target_name": "{{ event.data.target_name}}",
"event.data.target_id": "{{ event.data.target_id}}",
"event.data.failure_reason": "{{ event.data.failure_reason}}"
},
"Message Data": {
"message.id": "{{ message.id }}",
"message.name": "{{ message.name }}",
"message.title": "{{ message.title.en }}",
"message.contents": "{{ message.contents.en }}",
"message.template_id": "{{ message.template_id }}",
"message.url": "{{ message.url }}",
"message.app_url": "{{ message.app_url }}",
"message.web_url": "{{ message.web_url }}"
}
}
```
#### Usando Sintaxis Liquid en JSON
Cuando usas sintaxis Liquid dentro de JSON, el uso apropiado de comillas depende del tipo de datos:
**Directrices para formateo JSON**
* **Cadenas** → **Deben** envolverse en comillas.
* **Números** → **No** envolver en comillas.
* **Objetos** → **No deben** envolverse en comillas.
Las líneas de comentario `//` en los ejemplos **Correctos** a continuación son solo para legibilidad. Elimínalas en el cuerpo real de tu Event Stream — el JSON estricto no permite comentarios `//`.
**Ejemplos**
**✅ Correcto** — envolver en comillas:
```liquid JSON theme={null}
{
"user_id": "{{ user.onesignal_id }}"
}
```
**❌ Incorrecto** — la falta de comillas produce JSON inválido:
```liquid JSON theme={null}
{
"user_id": {{ user.onesignal_id }}
}
```
**✅ Correcto** — sin comillas:
```liquid JSON theme={null}
{
"user_score": {{ user.tags.score }}
}
```
**❌ Incorrecto** — las comillas convierten el número en una cadena:
```liquid JSON theme={null}
{
"user_score": "{{ user.tags.score }}"
}
```
**✅ Correcto** — sin comillas:
```liquid JSON theme={null}
{
"user_data": {{ user.tags }}
}
```
**❌ Incorrecto** — las comillas convierten el objeto en una cadena:
```liquid JSON theme={null}
{
"user_data": "{{ user.tags }}"
}
```
**Mejores prácticas para manejar condicionales multilingües en sintaxis liquid**
Para evitar problemas con condicionales basados en idioma
1. **Usa verificaciones directas de idioma**: Siempre verifica `user.language` directamente en los condicionales, no en variables como `userLang`, para mejor compatibilidad.
2. **Comienza simple**: Empieza con frases básicas, luego agrega complejidad gradualmente.
3. **Evita el anidamiento excesivo**: Mantén los condicionales planos para prevenir problemas de análisis.
4. **Prueba la puntuación básica primero**: Comienza con oraciones simples y puntuación antes de usar caracteres especiales.
5. **Usa respaldos**: Asegura un idioma predeterminado (por ejemplo, inglés) en caso de traducciones faltantes.
6. **Apégate a claves estándar**: Usa claves estándar de OneSignal como `content/title/en` para confiabilidad.
Este enfoque minimiza los errores de análisis y asegura la compatibilidad con el sistema.
Para detalles y opciones sobre cómo personalizar tus mensajes usando sintaxis Liquid, consulta nuestra [Guía de Uso de Sintaxis Liquid](./using-liquid-syntax).
***
## Resultados y depuración
Monitoreo del rendimiento de tu Event Stream y solución de problemas:
**Pestaña de informe** — Muestra los totales de todos los tiempos, el estado actual de tu event stream y un gráfico de series temporales de códigos de respuesta HTTP a lo largo del tiempo.
| Respuesta | Significado |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| **2xx** | El evento fue recibido exitosamente por tu endpoint. |
| **4xx / 5xx** | Tu endpoint devolvió un error. Revisa la pestaña Registros para el código de estado específico y el cuerpo de la respuesta. |
| **Tiempo de espera** | Tu endpoint no respondió dentro de la ventana permitida. OneSignal cerró la conexión y trató la entrega como fallida. |
**Pestaña de registros** — Muestra una muestra de solicitudes recientes, incluyendo el cuerpo completo de la solicitud, encabezados y la respuesta de tu endpoint. Este es el mejor lugar para comenzar al depurar — puedes ver exactamente qué envió OneSignal y qué devolvió tu servidor.
Si el payload o la configuración necesita ajuste, edita el event stream y usa el botón **Enviar Prueba** para enviar solicitudes de muestra. Itera hasta que el payload coincida con lo que espera tu endpoint, luego ve en vivo.
### Reintentos / Deshabilitación
**Comportamiento de reintentos** — Cuando una solicitud falla con un estado recuperable (p. ej. `429`), OneSignal reintenta con retrasos crecientes. Si los reintentos para un solo evento siguen fallando, ese evento se marca como permanentemente fallido y no se reintenta más.
**Deshabilitación automática** — Si tu endpoint devuelve fallos sostenidos en muchos eventos, OneSignal puede deshabilitar todo el event stream. Cuando esto sucede:
1. Los administradores de la aplicación y la organización reciben un correo electrónico cuando el volumen de fallos se vuelve significativo (antes de deshabilitar) y nuevamente cuando el stream se deshabilita.
2. También aparece un banner en la página de índice de **Event Streams** en el panel.
3. Soluciona el problema subyacente, prueba con la pestaña **Registros** o [webhook.site](https://webhook.site) y vuelve a habilitar el stream.
**Orientación sobre rendimiento** — Tu endpoint debe poder manejar el volumen de eventos que producen tus envíos de mensajes. Para evitar retrasos y deshabilitación:
* **Registra eventos rápidamente** — Escribe el evento entrante en una cola o almacén de datos sin procesamiento inline pesado.
* **Evita respuestas lentas y 429s** — Los tiempos de respuesta consistentemente lentos o las respuestas de límite de tasa hacen que los eventos se acumulen, lo que lleva a OneSignal a deshabilitar el stream.
* **Dimensiona para tu volumen de envío** — Si envías 100k mensajes, espera hasta 100k eventos por tipo de evento seleccionado. Revisa el volumen de mensajes de tu plan y aprovisiona en consecuencia.
**Deduplicación** — Cada evento entregado incluye un `event.id` único. Inclúyelo en un encabezado o en el cuerpo JSON para que tu sistema pueda deduplicar si el mismo evento se reintenta o reproduce.
### Consejos para el éxito
* **Apunta los streams a tus propios servidores primero.** Puedes *conectarte* directamente a una API de terceros, pero el depurado, el manejo de límites de tasa y la gestión de volumen son más difíciles cuando no controlas el extremo receptor.
* **Almacena en búfer antes de enviar a terceros.** OneSignal envía eventos tan rápido como los usuarios los activan — un envío grande puede producir una ráfaga que abruma los límites de tasa externos o aumenta los costos (especialmente con proveedores de SMS). Construye un servicio ligero que acepte eventos, los ponga en cola y los reenvíe a APIs externas a un ritmo que controles.
* **Consulta los documentos de la API de terceros.** Muchos servicios exponen APIs HTTP públicas a las que puedes apuntar con un event stream. Busca sus documentos sobre autenticación, formato de payload aceptado y límites de tasa antes de configurar tu stream.
### Limitaciones de datos de eventos de mensajes
Los datos de mensajes enviados mediante nuestros Journeys o API solo están disponibles en OneSignal durante 30 días. Esto significa que cualquier evento de mensaje (como clics, aperturas, cancelaciones de suscripción, etc.) que ocurra 30+ días después de que se envió el mensaje de Journey o API, no estará disponible en el event stream. Esto puede aparecer como datos en blanco o faltantes en tus análisis.
Para solucionar esta limitación, puedes correlacionar el `message.id` de estos eventos de clic/apertura/cancelación de suscripción con el evento `sent` original que tiene el mismo `message.id`. El evento `sent` original debería tener los datos de mensaje relevantes (título, plantilla, etc.).
***
## Pruebas
Guía de pruebas de extremo a extremo usando [webhook.site](https://webhook.site). Pega **Your unique URL** en el campo **URL** del Event Stream con el método **POST**.
Establece los eventos que deseas rastrear. En este ejemplo, usaremos los eventos push, pero cualquiera funcionará.
En este ejemplo, usaremos el [Ejemplo de cuerpo](#body) anterior.
Guarda el evento y ponlo en vivo.
Envía un mensaje para activar el evento. En webhook.site veremos el evento con los siguientes datos:
Esto muestra lo siguiente:
* **Host**: la dirección IP de donde provino la solicitud. Consulta [Descripción general de la API REST](/reference/rest-api-overview) para una lista de IPs posibles.
* **Request Content** los datos enviados dentro del cuerpo del event stream.
***