Visão geral
Web Push Webhooks permitem que você receba notificações HTTP POST em tempo real sempre que usuários interagem com suas notificações push. Quando uma notificação é exibida, clicada ou dispensada, OneSignal envia automaticamente os dados da notificação e quaisquer parâmetros personalizados para a URL webhook especificada.
Benefícios Principais:
- Rastreie engajamento de notificação em tempo real
- Acione workflows automatizados baseados em interações de usuário
- Sincronize dados de notificação com sua plataforma de analytics
- Implemente lógica de negócios personalizada para eventos de notificação
Suporte de Navegador
| Browser | Platform Support | Webhook Events Available |
|---|
| Chrome | macOS, Windows, Android | Todos os eventos (exibir, clicar, dispensar) |
| Firefox | macOS, Windows, Android | Eventos de exibição e clique |
| Safari | Não suportado | Nenhum |
Eventos de Webhook Disponíveis
notification.willDisplay
Acionado imediatamente após uma notificação aparecer na tela do usuário.
Casos de uso: Rastreie taxas de entrega, registre dados de impressão, acione campanhas de acompanhamento
notification.clicked
Acionado quando um usuário clica no corpo da notificação ou em qualquer botão de ação.
Casos de uso: Rastreie taxas de engajamento, acione eventos de conversão, redirecione usuários para conteúdo específico
notification.dismissed
Acionado quando um usuário dispensa ativamente uma notificação ou quando ela expira automaticamente.
Suporte de navegador: Apenas Chrome
Casos de uso: Rastreie taxas de dispensação, otimize tempo de notificação, teste A/B de conteúdo de notificação
Importante: Clicar no corpo da notificação ou botões de ação NÃO aciona o webhook dispensado.
Métodos de Configuração
Navegue para Settings > Web no seu dashboard OneSignal
Habilite o toggle “Enable webhooks”
Insira suas URLs webhook para cada evento que você deseja rastrear
Adicione configuração de webhook ao seu método OneSignal.init() existente:// Add to your existing OneSignal initialization - do NOT call init twice
OneSignal.init({
// Your other existing settings here
webhooks: {
cors: false, // Recommended: leave as false unless you need custom headers
'notification.willDisplay': 'https://yoursite.com/webhook/display',
'notification.clicked': 'https://yoursite.com/webhook/click',
'notification.dismissed': 'https://yoursite.com/webhook/dismiss' // Chrome only
}
});
Certifique-se de que suas URLs webhook sejam HTTPS (necessário pelas políticas de segurança do Chrome).
Configuração CORS
A configuração cors determina quais headers e dados seu endpoint webhook recebe:
cors: false (Recomendado): Configuração mais simples, nenhuma configuração CORS necessária no seu servidorcors: true: Fornece headers adicionais mas requer suporte CORS no seu servidor
Quando usar cors: true:
- Você precisa do header
Content-Type: application/json
- Você quer o header
X-OneSignal-Event para identificação de evento mais fácil
- Seu servidor já suporta CORS para requisições não-simples
Requisição Padrão (cors: false)
Seu endpoint webhook recebe uma requisição POST com esta estrutura de payload:
{
"event": "notification.clicked",
"notificationId": "ed46884e-0e3f-4373-9e11-e28f27746d3d",
"heading": "Your notification title",
"content": "Your notification message",
"additionalData": {
"userId": "12345",
"campaignId": "summer-sale",
"customField": "customValue"
},
"actionId": "buy-now-button",
"url": "https://yoursite.com/product/123"
}
Requisição Aprimorada (cors: true)
Mesmo payload acima, mais estes headers adicionais:
Content-Type: application/json
X-OneSignal-Event: notification.clicked
Referência de Campos do Payload
| Field | Type | Description | Always Present |
|---|
event | string | Tipo de evento que acionou o webhook | ✅ |
notificationId | string | Identificador único de notificação OneSignal | ✅ |
heading | string | Título da notificação | Apenas se fornecido |
content | string | Corpo da mensagem da notificação | Apenas se fornecido |
additionalData | object | Dados personalizados enviados com a notificação | Apenas se fornecido |
actionId | string | ID do botão de ação clicado (string vazia = corpo da notificação clicado) | Apenas eventos de clique |
url | string | URL de lançamento para a notificação | Apenas se fornecido |
subscriptionId | string | ID de usuário/subscription OneSignal | Apenas com CORS habilitado |
Melhores Práticas de Implementação
Requisitos do Endpoint Webhook
Segurança:
- Use URLs HTTPS apenas (URLs HTTP serão bloqueadas pelo Chrome)
- Implemente autenticação/validação adequada para seus endpoints webhook
- Considere limitação de taxa para lidar com notificações de alto volume
Requisitos de Resposta:
- Retorne status HTTP 200 para processamento bem-sucedido
- Responda dentro de 10 segundos para evitar timeouts
- Lide com chamadas de webhook duplicadas graciosamente (implemente idempotência)
Tratamento de Erros
// Example webhook endpoint (Node.js/Express)
app.post('/webhook/notification', (req, res) => {
try {
const { event, notificationId, additionalData } = req.body;
// Validate required fields
if (!event || !notificationId) {
return res.status(400).json({ error: 'Missing required fields' });
}
// Process the webhook data
processNotificationEvent(req.body);
// Always respond with 200 OK
res.status(200).json({ success: true });
} catch (error) {
console.error('Webhook processing error:', error);
res.status(500).json({ error: 'Internal server error' });
}
});
Problemas Comuns e Soluções
Webhooks Não Disparam
Causas possíveis:
- Código de webhook não presente em todas as páginas com inicialização OneSignal
- Usuário não visitou uma página com código webhook após ele ser adicionado
- Requisito HTTPS não atendido
- Servidor retornando códigos de status não-200
Solução: Garanta que a configuração de webhook está incluída no seu código init OneSignal em todas as páginas onde notificações estão ativas.
Dados Ausentes em Webhooks
Causa: Webhooks rastreiam apenas eventos para usuários que visitam páginas com a configuração de webhook ativa.
Solução: Implante código webhook em todas as páginas com OneSignal, não apenas páginas de destino específicas.
Chamadas de Webhook Duplicadas
Causa: Problemas de rede ou comportamento do navegador podem causar requisições duplicadas.
Solução: Implemente idempotência usando o campo notificationId para deduplicar eventos.
Limitações de Webhook
- Uma URL webhook por evento: Você não pode definir múltiplas URLs webhook para o mesmo tipo de evento
- Apenas HTTPS: URLs HTTP não funcionarão devido a restrições de segurança do navegador
- Rastreamento de dispensação apenas no Chrome: O evento
notification.dismissed funciona apenas no Chrome
- Dependência de página: Usuários devem visitar páginas com código webhook ativo para rastreamento funcionar
Testando Seus Webhooks
- Envie uma notificação de teste através do seu dashboard OneSignal
- Monitore seu endpoint webhook para requisições recebidas
- Verifique estrutura do payload corresponde às suas expectativas
- Teste diferentes cenários:
- Exibição de notificação
- Clique no corpo da notificação
- Clique em botões de ação (se configurados)
- Dispensação de notificações (apenas Chrome)
Próximos Passos
Após configurar webhooks, considere:
- Integração de Analytics: Encaminhe dados de webhook para sua plataforma de analytics
- Segmentação de Usuário: Use eventos de webhook para criar segmentos de usuário baseados em engajamento
- Workflows Automatizados: Acione campanhas de email ou notificações de app baseadas em interações de notificação push
- Teste A/B: Use dados de webhook para medir a eficácia de diferentes estratégias de notificação
