Pular para o conteúdo principal

​
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.
Para webhooks de Journey, veja nossa página Journey webhooks.
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

BrowserPlatform SupportWebhook Events Available
ChromemacOS, Windows, AndroidTodos os eventos (exibir, clicar, dispensar)
FirefoxmacOS, Windows, AndroidEventos de exibição e clique
SafariNão suportadoNenhum

​
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

  • 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

Habilite webhooks nas configurações do seu dashboard OneSignal

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 servidor
  • cors: 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

​
Formato de Requisição Webhook

​
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

FieldTypeDescriptionAlways Present
eventstringTipo de evento que acionou o webhook✅
notificationIdstringIdentificador único de notificação OneSignal✅
headingstringTítulo da notificaçãoApenas se fornecido
contentstringCorpo da mensagem da notificaçãoApenas se fornecido
additionalDataobjectDados personalizados enviados com a notificaçãoApenas se fornecido
actionIdstringID do botão de ação clicado (string vazia = corpo da notificação clicado)Apenas eventos de clique
urlstringURL de lançamento para a notificaçãoApenas se fornecido
subscriptionIdstringID de usuário/subscription OneSignalApenas 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

  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

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