Event Streams

• 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

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 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 com sintaxe Liquid.
4. Testar de ponta a ponta — Use webhook.site para verificar o formato do payload e os cabeçalhos antes de mudar para seu endpoint de produção (consulte Testes).

​

Configuração

• 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

​

Filtros de event stream

​

Configurar o Event Stream

​

Cabeçalhos de Autenticação

• 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}}

​

Testando Sua Configuração

​

Cabeçalhos não permitidos

• content-length
• referer
• metadata-flavor
• x-google-metadata-request
• host
• x-onesignal*

​

Corpo

​

Personalização

​

Exemplo de corpo

{
  "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

• Strings → Devem ser envolvidas em aspas.
• Números → Não envolver em aspas.
• Objetos → Não devem ser envolvidos em aspas.

{
  "user_id": "{{ user.onesignal_id }}"
}

{
  "user_id": {{ user.onesignal_id }}
}

{
  "user_score": {{ user.tags.score }}
}

{
  "user_score": "{{ user.tags.score }}"
}

{
  "user_data": {{ user.tags }}
}

{
  "user_data": "{{ user.tags }}"
}

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.

​

Resultados e Depuração

​

Tentativas / Desabilitação

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, e reabilite o stream.

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

​

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

​

Testes

• Host: o endereço IP de onde a solicitação veio. Consulte Visão geral da API REST para uma lista de IPs possíveis.
• Request Content: os dados enviados dentro do corpo do event stream.