> ## 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.
# Webhooks de web push
> Configure webhooks HTTP para receber notificações em tempo real quando usuários exibem, clicam ou dispensam notificações web push. Guia completo com exemplos para suporte de navegadores Chrome, Firefox e Safari.
## 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](./journeys-webhook).
**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:
```javascript theme={null}
// 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 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:
```json theme={null}
{
"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:
```http theme={null}
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
```javascript theme={null}
// 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