Pular para o conteúdo principal
Webhooks de Journey enviam requisições HTTP de uma etapa de Journey para seus servidores ou qualquer endpoint publicamente acessível. Você configura o método HTTP, URL, cabeçalhos e conteúdo do corpo. As requisições podem ser personalizadas com dados específicos do usuário usando sintaxe Liquid, permitindo que você sincronize eventos de Journey com CRMs, plataformas de análise ou backends personalizados em tempo real.

​
Requisitos

  • Entre em contato com a equipe de vendas do OneSignal para acesso.
  • A URL ou endereço IP deve ser válido e acessível via HTTP ou HTTPS.
  • Os endpoints devem ser publicamente roteáveis — não atrás de um firewall ou em localhost.
  • Os domínios devem ter um domínio de nível superior válido (.com, .org, .net, etc.).
Webhooks de Journey não podem chamar APIs do OneSignal. Eles são projetados apenas para enviar dados a sistemas externos.

​
Configuração

Uma vez que sua Journey esteja criada, siga estas etapas:
  1. Navegue até Data > Webhooks no painel do OneSignal.
  2. Clique para criar um novo webhook.
  3. Defina o seguinte:
    • Método HTTP (geralmente POST)
    • URL de destino
    • Cabeçalhos personalizados (por exemplo, tokens de autenticação)
    • Conteúdo do corpo (texto simples ou JSON, opcionalmente usando Liquid)
Formulário de configuração do webhook com campos de método HTTP, URL, cabeçalhos e corpo

​
Cabeçalhos não permitidos

Você não pode definir os seguintes cabeçalhos:
  • content-length
  • referer
  • metadata-flavor
  • x-google-metadata-request
  • host
  • Qualquer cabeçalho começando com x-onesignal

​
Testando webhooks

Você também pode testar seu endpoint manualmente usando uma ferramenta como curl: 
curl -X POST https://yourserver.com/webhook \
  -H "Content-Type: application/json" \
  -d '{ "user_id": "abc123" }'
Isso valida que seu endpoint está acessível e funcionando antes de adicioná-lo a uma Journey.

​
Personalização

Todos os campos de webhook suportam sintaxe Liquid, permitindo que você insira dinamicamente dados de usuário e assinatura na requisição. Consulte Personalização de mensagens para a lista completa de propriedades disponíveis.

​
Referência de dados do usuário

As seguintes propriedades do objeto user estão disponíveis em campos de webhook via sintaxe Liquid:
PropriedadeTipoUsoDisponível em Teste?
OneSignal IDString{{ user.onesignal_id }}✅
External IDString{{ user.external_id }}✅
TagsObject{{ user.tags.your_tag_key_here }}❌
LanguageString{{ user.language }}✅
Tags não estão disponíveis ao testar webhooks fora de uma Journey ativa. Use Assinaturas de teste para validar o comportamento antes de ativar.

​
Adicionando um webhook a uma Journey

  1. Após criar e testar seu webhook, abra sua Journey.
  2. Adicione uma etapa de Webhook onde necessário.
  3. Selecione o webhook que você configurou anteriormente.
Cada vez que um usuário alcançar essa etapa, o webhook é acionado com seus dados personalizados.
Canvas de Journey com uma etapa de webhook conectada entre etapas de mensagem

​
Debug e logs

​
Estatísticas de webhook

Vá para a aba Stats do webhook para ver como seu webhook está performando. Isso inclui:
  • Total de eventos enviados
  • Tendências de tempo de resposta
  • Distribuição de código de status
Aba de estatísticas do webhook com contagem de eventos, tendências de tempo de resposta e distribuição de código de status

​
Aba de Logs

Para insights mais granulares, a aba Logs exibe:
  • Dados de requisição/resposta recentes
  • Códigos de status e mensagens de erro
  • Cabeçalhos e payloads (onde aplicável)
Aba de logs do webhook com requisições recentes, códigos de status e payloads

​
Lógica de tentativa e comportamento de desabilitação

O OneSignal tenta novamente requisições de webhook que falharam para erros recuperáveis (como 429 Too Many Requests). As tentativas acontecem com atrasos crescentes entre as tentativas. Se as tentativas falharem repetidamente, o webhook é marcado como permanentemente falhado e nenhuma tentativa adicional é feita.

​
Desabilitação automática

Se um webhook falha consistentemente, o OneSignal o desabilita para evitar problemas adicionais. Os administradores recebem alertas por email e um banner no painel antes e depois da desabilitação. Identifique a causa raiz e teste o webhook antes de reabilitá-lo. Seu endpoint deve lidar com o volume de eventos que sua Journey produz. Revise o volume de envio de mensagens do seu app para estimar o throughput de que sua API precisa.

​
Orientação de desempenho

  • Endpoints lentos ou sobrecarregados (especialmente aqueles retornando respostas 429) podem acionar a desabilitação automática.
  • Registre eventos rapidamente e adie processamento adicional para evitar timeouts.
  • O volume escala com a atividade do usuário — certifique-se de que seu endpoint pode lidar com o throughput de pico.
  • Use o valor event.id (disponível como cabeçalho ou no corpo) para deduplicar eventos recebidos.

​
Melhores práticas de confiabilidade

  • Roteie primeiro pelo seu próprio servidor, não diretamente para serviços de terceiros. Isso lhe dá controle sobre logging, autenticação, throttling e enfileiramento. Serviços de terceiros podem limitar ou bloquear requisições durante picos de volume, e o OneSignal não gerencia esses limites.
  • Planeje para bursts. A execução de webhook acontece imediatamente quando os usuários alcançam a etapa. Se muitos usuários atingirem uma etapa de webhook de uma vez, o OneSignal envia uma rajada de requisições HTTP sem limitação de taxa. Considere construir uma camada de API leve ou proxy de enfileiramento que possa ingerir webhooks de forma confiável, aplicar limites de taxa ou lotes, e rotear requisições para serviços de terceiros de forma adequada.
  • Revise os limites de API de terceiros. Ferramentas populares como Slack, Twilio e Segment oferecem APIs HTTP públicas, mas têm seus próprios limites de taxa, requisitos de autenticação e tratamento de erros. Verifique a documentação deles antes de conectar diretamente.

​
Protegendo seu webhook

Para verificar que as requisições estão vindo do OneSignal e não foram adulteradas:
  • Assinatura HMAC: Inclua um segredo compartilhado na configuração do webhook. O OneSignal assina cada requisição com um cabeçalho HMAC que seu servidor pode validar antes de processar o payload.
  • Token de autenticação personalizado: Adicione um cabeçalho de autorização personalizado (por exemplo, Authorization: Bearer SEU_TOKEN_SECRETO) e verifique-o no lado do servidor antes de aceitar a requisição.

​
FAQ

​
Posso usar webhooks para chamar APIs do OneSignal?

Não. Webhooks de Journey são projetados apenas para enviar dados a sistemas externos. Eles não podem chamar APIs do OneSignal. Para atualizar dados do OneSignal com base em eventos de Journey, roteie o webhook pelo seu próprio servidor e faça seu servidor chamar a API do OneSignal.

​
Por que meu webhook foi desabilitado automaticamente?

O OneSignal desabilita webhooks que falham consistentemente para evitar problemas adicionais. Verifique a aba Logs para detalhes de erro (códigos de status, corpos de resposta), corrija a causa raiz e teste o webhook antes de reabilitá-lo. Causas comuns incluem inatividade do endpoint, erros de autenticação e limitação de taxa.

​
Como faço para deduplicar eventos de webhook?

Use o valor event.id (disponível como cabeçalho ou no corpo da requisição) para identificar eventos únicos. Armazene IDs de eventos processados no seu servidor e pule qualquer duplicata. Isso é especialmente importante se as tentativas entregarem o mesmo evento mais de uma vez.

​
As requisições de webhook são limitadas pelo OneSignal?

Não. O OneSignal envia requisições de webhook imediatamente quando os usuários alcançam a etapa, sem limitação de taxa. Se muitos usuários atingirem uma etapa de webhook de uma vez, seu endpoint recebe uma rajada de requisições. Construa seu endpoint para lidar com o volume de pico, ou use um proxy de enfileiramento para fazer buffer e lotes de requisições.

​
Posso testar webhooks sem lançar uma Journey?

Sim. Use o botão Teste na configuração do webhook para enviar uma requisição de amostra. Observe que tags não estão disponíveis em requisições de teste — use assinaturas de teste em uma Journey ativa para validação completa.

​
Páginas relacionadas

Visão geral de Journeys

Introdução às Journeys e como os fluxos multicanais funcionam.

Ações de Journey

Adicione etapas de espera, lógica de ramificação, janelas de tempo e caminhos divididos.

Sintaxe Liquid

Referência completa para templates Liquid em mensagens e webhooks do OneSignal.

Personalização de mensagens

Visão geral de todos os métodos de personalização incluindo tags, Liquid e conteúdo dinâmico.