> ## 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
> Envie dados de mensagem para fora do OneSignal em tempo real para o destino escolhido.
Event Streams permite que você envie dados de mensagem para fora do OneSignal em tempo real para o destino escolhido. Event streams são uma ótima maneira de conectar o OneSignal a outros produtos dentro do seu ecossistema de marketing. Eles permitem que sua equipe acione mensagens correspondentes, mantenha registros e muito mais.
Os tipos de eventos disponíveis incluem:
* Eventos de mensagens push (enviadas, recebidas, clicadas, falharam, cancelamento de inscrição)
* Eventos de email (enviados, abertos, clicados, rejeitados, cancelamento de inscrição, etc.)
* Eventos de SMS (enviados, falharam, cancelamento de inscrição, etc.)
* Eventos de mensagens in-app (impressão, clicadas, etc.)
* Eventos de Live Activity (enviadas, entregues, entrega confirmada, falharam, cancelamento de inscrição, clicadas)
## Casos de uso comuns
* **Centralizar dados de engajamento** — Transmita eventos para um CRM, CDP ou data warehouse para que a atividade entre canais (aberturas, cliques, rejeições) fique em um único lugar em vez de distribuída entre ferramentas desconectadas.
* **Análises, relatórios e conformidade** — Armazene cada evento de mensagem em um warehouse para análise de tendências, auditoria ou manutenção de registros regulatórios.
* **Monitorar o desengajamento** — Acompanhe cancelamentos de inscrição, rejeições e dispensas em seus próprios sistemas para detectar riscos de retenção cedo.
* **Acionar fluxos de trabalho externos** — Dispare automações em outras ferramentas quando um usuário abre ou clica em uma mensagem (p. ex., atualizar uma pontuação de lead, iniciar uma sequência de acompanhamento).
* **Substituir sincronizações em lote e integrações extras** — Reaja a eventos em tempo real e conecte o OneSignal diretamente ao seu destino, reduzindo ferramentas intermediárias e custos de manutenção.
### Iniciando sua equipe técnica
Configurar Event Streams é um esforço conjunto entre o proprietário de marketing/produto (que decide *quais* eventos importam e *para onde* vão) e a equipe de engenharia (que constrói o endpoint receptor e configura o stream). Veja o que envolve o lado da engenharia:
1. **Decidir sobre um destino e escopo** — Concordar sobre onde os eventos devem chegar (sua própria API, um data warehouse, um CDP, etc.), quais tipos de eventos transmitir (push, email, SMS, IAM, Live Activity) e uma estimativa do volume de mensagens para que o endpoint tenha o dimensionamento adequado.
2. **Configurar um endpoint HTTP** — Construir ou configurar um endpoint acessível publicamente que aceite solicitações POST. Ele deve registrar eventos rapidamente sem processamento pesado para manter os tempos de resposta baixos. Consulte [Tentativas / Desabilitação](#retries--disabling) para expectativas de desempenho e o que acontece quando o endpoint fica para trás.
3. **Configurar o Event Stream no OneSignal** — Em **Dados > Event Streams**, selecione eventos, defina a URL e os cabeçalhos de autenticação e defina o corpo JSON usando campos de [Dados de Event Streams](./event-streams-data) com [sintaxe Liquid](./using-liquid-syntax).
4. **Testar de ponta a ponta** — Use [webhook.site](https://webhook.site) para verificar o formato do payload e os cabeçalhos antes de mudar para seu endpoint de produção (consulte [Testes](#testing)).
***
## Configuração
Você pode configurar um novo event stream para seu aplicativo OneSignal em **Dados > Event Streams > Novo Event Stream**.
**Requisitos**
Eventos não podem ser enviados a menos que os seguintes requisitos sejam atendidos:
* Uma URL ou endereço IP válido para um **endpoint HTTP(S)** acessível publicamente
* URLs e endereços IP devem ser publicamente roteáveis
* Domínios devem incluir um domínio de nível superior reconhecido (por exemplo, ".com", ".net")
### Seleção de Evento
Nomeie seu Event Stream e clique em **Selecionar Eventos**.
Isso abrirá a página de Seleção de Eventos onde você pode selecionar os eventos que deseja acionar seu event stream.
Cada evento conta para o volume de eventos de mensagens do seu plano. Transmitir **cada** tipo de evento (especialmente `sent`) para um grande público pode consumir sua cota rapidamente — por exemplo, um único envio para 100.000 usuários gera 100.000 eventos `sent` sozinho.
Para gerenciar o volume:
* **Selecione apenas os tipos de eventos que você precisa** — p. ex., `received` e `clicked` podem ser suficientes se você não precisar de rastreamento em nível de envio.
* **Use [filtros de event stream](#event-stream-filters)** para limitar eventos a mensagens ou modelos específicos em vez de transmitir todo o tráfego.
#### Filtros de event stream
Você pode opcionalmente refinar ainda mais os eventos especificando os identificadores de uma ou mais mensagens ou modelos, permitindo que você receba apenas eventos relacionados a mensagens específicas.
Os identificadores de modelo podem ser copiados navegando até **Mensagens > Modelos**. Ao lado do modelo que você deseja rastrear, selecione **Opções > Copiar ID do Modelo** e cole nos filtros do Event Stream.
### Configurar o Event Stream
Selecione o método HTTP, a URL e adicione cabeçalhos para o event stream. É aqui que a autenticação deve ser configurada para garantir comunicação segura entre o OneSignal e seus sistemas.
A URI e os Cabeçalhos podem conter sintaxe liquid que virá tanto das propriedades do usuário quanto das propriedades do event stream.
#### Cabeçalhos de Autenticação
Você pode adicionar cabeçalhos de autenticação para validar que as solicitações ao seu endpoint são genuinamente do OneSignal. Métodos comuns de autenticação incluem:
* **Cabeçalho de Autorização**: Adicione um cabeçalho `Authorization`, onde `YOUR_TOKEN` é fornecido pelo seu sistema ou terceiros como:
* `Basic {{YOUR_TOKEN}}`
* `Bearer {{YOUR_TOKEN}}`
* `ApiKey {{YOUR_API_KEY}}`
* **Cabeçalhos Personalizados**: Você também pode adicionar cabeçalhos personalizados como:
* `X-API-Key: {{YOUR_API_KEY}}`
*Nota: O OneSignal não fornece serviços de criptografia*
#### Testando Sua Configuração
Se você está procurando uma maneira fácil de testar, use [webhook.site](https://webhook.site). Encontre "Your unique URL" no centro da página. Copie essa URL e use-a no campo URL da configuração do seu event stream.
#### Cabeçalhos não permitidos
Os seguintes cabeçalhos são restritos e não podem ser definidos.
* `content-length`
* `referer`
* `metadata-flavor`
* `x-google-metadata-request`
* `host`
* `x-onesignal*`
### Corpo
O corpo de um event stream será JSON. O JSON do corpo pode ser definido como pares chave/valor individuais ou como um bloco de código editável. Para alterar o método de entrada, use o primeiro menu suspenso sob o título do corpo e selecione o corpo personalizado.
À direita, você pode ver um exemplo de solicitação cURL construído a partir do que foi inserido durante a configuração do event stream
### Personalização
Você pode personalizar todos os campos no seu Event Stream com [Dados de Event Streams](./event-streams-data) predefinidos. Esses dados podem ser adicionados usando [Sintaxe Liquid](./using-liquid-syntax). Isso dá a você a flexibilidade de usar event streams para praticamente qualquer caso de uso.
Consulte [Dados de Event Streams](./event-streams-data) para uma lista de todos os dados de evento, mensagem e evento de usuário disponíveis para personalização.
#### Exemplo de corpo
Selecione o "Corpo Personalizado" no menu suspenso:
```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 Sintaxe Liquid em JSON
Ao usar sintaxe Liquid dentro de JSON, a citação adequada depende do tipo de dados:
**Diretrizes para Formatação JSON**
* **Strings** → **Devem** ser envolvidas em aspas.
* **Números** → **Não** envolver em aspas.
* **Objetos** → **Não devem** ser envolvidos em aspas.
As linhas de comentário `//` nos exemplos **Corretos** abaixo são apenas para legibilidade. Remova-as no corpo real do seu Event Stream — o JSON estrito não permite comentários `//`.
**Exemplos**
**✅ Correto** — envolver em aspas:
```liquid JSON theme={null}
{
"user_id": "{{ user.onesignal_id }}"
}
```
**❌ Incorreto** — a falta de aspas produz JSON inválido:
```liquid JSON theme={null}
{
"user_id": {{ user.onesignal_id }}
}
```
**✅ Correto** — sem aspas:
```liquid JSON theme={null}
{
"user_score": {{ user.tags.score }}
}
```
**❌ Incorreto** — aspas transformam o número em uma string:
```liquid JSON theme={null}
{
"user_score": "{{ user.tags.score }}"
}
```
**✅ Correto** — sem aspas:
```liquid JSON theme={null}
{
"user_data": {{ user.tags }}
}
```
**❌ Incorreto** — aspas transformam o objeto em uma string:
```liquid JSON theme={null}
{
"user_data": "{{ user.tags }}"
}
```
**Melhores práticas para lidar com condicionais multilíngues na sintaxe liquid**
Para evitar problemas com condicionais baseados em idioma
1. **Use Verificações Diretas de Idioma**: Sempre verifique `user.language` diretamente em condicionais, não em variáveis como `userLang`, para melhor compatibilidade.
2. **Comece Simples**: Comece com frases básicas e, em seguida, adicione complexidade gradualmente.
3. **Evite Aninhamento Excessivo**: Mantenha as condicionais planas para evitar problemas de análise.
4. **Teste a Pontuação Básica Primeiro**: Comece com frases e pontuação simples antes de usar caracteres especiais.
5. **Use Valores Padrão**: Garanta um idioma padrão (por exemplo, inglês) em caso de traduções ausentes.
6. **Atenha-se às Chaves Padrão**: Use chaves padrão do OneSignal como `content/title/en` para confiabilidade.
Essa abordagem minimiza erros de análise e garante compatibilidade com o sistema.
Para detalhes e opções sobre como personalizar suas mensagens usando sintaxe Liquid, confira nosso [Guia de Uso de Sintaxe Liquid](./using-liquid-syntax).
***
## Resultados e Depuração
Monitorando o desempenho do seu Event Stream e solucionando problemas:
**Aba de Relatório** — Exibe totais de todos os tempos, o status atual do seu event stream e um gráfico de séries temporais de códigos de resposta HTTP ao longo do tempo.
| Resposta | Significado |
| ------------- | ------------------------------------------------------------------------------------------------------------------ |
| **2xx** | O evento foi recebido com sucesso pelo seu endpoint. |
| **4xx / 5xx** | Seu endpoint retornou um erro. Verifique a aba de Logs para o código de status específico e o corpo da resposta. |
| **Timeout** | Seu endpoint não respondeu dentro da janela permitida. O OneSignal fechou a conexão e tratou a entrega como falha. |
**Aba de Logs** — Exibe uma amostra de solicitações recentes, incluindo o corpo completo da solicitação, cabeçalhos e a resposta do seu endpoint. Este é o melhor lugar para começar ao depurar — você pode ver exatamente o que o OneSignal enviou e o que seu servidor retornou.
Se o payload ou a configuração precisar de ajuste, edite o event stream e use o botão **Enviar Teste** para enviar solicitações de exemplo. Itere até que o payload corresponda ao que seu endpoint espera, depois coloque em produção.
### Tentativas / Desabilitação
**Comportamento de tentativas** — Quando uma solicitação falha com um status recuperável (p. ex. `429`), o OneSignal tenta novamente com atrasos crescentes. Se as tentativas para um único evento continuarem falhando, esse evento é marcado como permanentemente falho e não é mais tentado.
**Desabilitação automática** — Se seu endpoint retornar falhas sustentadas em muitos eventos, o OneSignal pode desabilitar todo o event stream. Quando isso acontece:
1. Administradores de aplicativos e de organizações recebem um email quando o volume de falhas se torna significativo (antes de desabilitar) e novamente quando o stream é desabilitado.
2. Um banner também aparece na página de índice de **Event Streams** no painel.
3. Corrija o problema subjacente, teste com a aba **Logs** ou [webhook.site](https://webhook.site), e reabilite o stream.
**Orientação de desempenho** — Seu endpoint deve ser capaz de lidar com o volume de eventos que seus envios de mensagens produzem. Para evitar acúmulos e desabilitação:
* **Registre eventos rapidamente** — Escreva o evento recebido em uma fila ou armazenamento de dados sem processamento inline pesado.
* **Evite respostas lentas e 429s** — Tempos de resposta consistentemente lentos ou respostas de limite de taxa fazem com que os eventos se acumulem, o que leva o OneSignal a desabilitar o stream.
* **Dimensione para seu volume de envio** — Se você enviar 100k mensagens, espere até 100k eventos por tipo de evento selecionado. Revise o volume de mensagens do seu plano e provisione adequadamente.
**Deduplicação** — Cada evento entregue inclui um `event.id` único. Inclua-o em um cabeçalho ou no corpo JSON para que seu sistema possa deduplicar se o mesmo evento for tentado novamente ou reproduzido.
### Dicas para Sucesso
* **Aponte streams para seus próprios servidores primeiro.** Você *pode* conectar diretamente a uma API de terceiros, mas depuração, tratamento de limites de taxa e gerenciamento de volume são mais difíceis quando você não controla a extremidade receptora.
* **Faça buffer antes de encaminhar para terceiros.** O OneSignal envia eventos tão rápido quanto os usuários os acionam — um envio grande pode produzir um pico que sobrecarrega os limites de taxa externos ou aumenta os custos (especialmente com provedores de SMS). Construa um serviço leve que aceite eventos, os coloque em fila e os encaminhe para APIs externas em um ritmo que você controla.
* **Verifique os docs de API de terceiros.** Muitos serviços expõem APIs HTTP públicas que você pode direcionar com um event stream. Procure a documentação sobre autenticação, formato de payload aceito e limites de taxa antes de configurar seu stream.
### Limitações de dados de eventos de mensagem
Os dados de mensagens enviadas por nossas Journeys ou API estão disponíveis no OneSignal apenas por 30 dias. Isso significa que quaisquer eventos de mensagem (como cliques, aberturas, cancelamentos de inscrição, etc.) que aconteçam 30+ dias após a mensagem de Journey ou API ser enviada, não estarão disponíveis no event stream. Isso pode aparecer como dados em branco ou ausentes em suas análises.
Para contornar essa limitação, você pode correlacionar o `message.id` desses eventos de clique/abertura/cancelamento de inscrição com o evento `sent` original que tem o mesmo `message.id`. O evento `sent` original deve ter os dados de mensagem relevantes (título, modelo, etc).
***
## Testes
Guia de testes de ponta a ponta usando [webhook.site](https://webhook.site). Cole **Your unique URL** no campo **URL** do Event Stream com o método **POST**.
Defina os eventos que você deseja rastrear. Neste exemplo, usaremos os eventos push, mas qualquer um funcionará.
Neste exemplo, usaremos o [Exemplo de corpo](#body) acima.
Salve o evento e coloque-o no ar.
Envie uma mensagem para acionar o evento. Em webhook.site veremos o evento com os seguintes dados:
Isso mostra o seguinte:
* **Host**: o endereço IP de onde a solicitação veio. Consulte [Visão geral da API REST](/reference/rest-api-overview) para uma lista de IPs possíveis.
* **Request Content**: os dados enviados dentro do corpo do event stream.
***