Webhooks de web push

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.

​

Visão geral

• 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

​

Eventos de Webhook Disponíveis

​

notification.willDisplay

​

notification.clicked

​

notification.dismissed

​

Métodos de Configuração

• Configuração do Dashboard (Recomendado para a Maioria dos Usuários)
• Integração com Código Personalizado

1

Navegue para Settings > Web no seu dashboard OneSignal

2

Habilite o toggle “Enable webhooks”

3

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
  }
});

​

Configuração CORS

• cors: false (Recomendado): Configuração mais simples, nenhuma configuração CORS necessária no seu servidor
• cors: true: Fornece headers adicionais mas requer suporte CORS no seu servidor

• 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

​

Formato de Requisição Webhook

​

Requisição Padrão (cors: false)

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

Content-Type: application/json
X-OneSignal-Event: notification.clicked

​

Referência de Campos do Payload

​

Melhores Práticas de Implementação

​

Requisitos do Endpoint Webhook

• 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

• 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

• 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

​

Dados Ausentes em Webhooks

​

Chamadas de Webhook Duplicadas

​

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

1. Envie uma notificação de teste através do seu dashboard OneSignal
2. Monitore seu endpoint webhook para requisições recebidas
3. Verifique estrutura do payload corresponde às suas expectativas
4. 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

• 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