Pular para o conteúdo principal
Com Webhooks de Journey, você pode enviar requisições HTTP de OneSignal Journeys para seus servidores—ou qualquer serviço acessível pela internet—no momento precisamente certo no ciclo de vida de um cliente. Configure o método HTTP, URL, cabeçalhos e conteúdo do corpo para corresponder aos seus requisitos de integração. Requisições podem ser dinamicamente personalizadas com dados específicos do usuário, tornando webhooks uma maneira poderosa de sincronizar suas Journeys com o resto do seu stack de marketing.

​
Requisitos

Antes que os eventos possam ser enviados, certifique-se de que:
  • Entre em contato com nossa equipe de vendas para acesso.
  • O endereço URL/IP é válido e alcançável via HTTP ou HTTPS.
  • Os endpoints são publicamente roteáveis (ou seja, não atrás de um firewall ou em localhost).
  • Os domínios devem ter um domínio de nível superior válido (por exemplo, .com, .org, .net).
  • Webhooks de Journey não podem ser usados para chamar APIs do OneSignal.

​
Configuração

Uma vez que sua Journey esteja criada, siga estes passos:
  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, para autenticação)
    • Conteúdo do corpo (texto simples ou JSON, opcionalmente usando Liquid)

Tela de configuração de webhook

​
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:
bash
curl -X POST https://yourserver.com/webhook \
  -H "Content-Type: application/json" \
  -d '{ "user_id": "abc123" }'
Útil para validar que seu endpoint está alcançá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. Veja Personalização de Mensagem para mais detalhes sobre as 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 }}❌
Idioma (Language)String{{ 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.

Uma etapa de webhook dentro de uma journey

​
Debug e logs

​
Estatísticas de webhook

Vá para a aba Stats do webhook para ver como seu webhook está tendo desempenho. Isso inclui:
  • Total de eventos enviados
  • Tendências de tempo de resposta
  • Distribuição de código de status

Página de relatórios do webhook

​
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)

Página de log do webhook

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

O OneSignal tenta novamente requisições de webhook que falharam para erros recuperáveis (por exemplo, 429 Too Many Requests). As tentativas acontecem com atrasos crescentes. 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 que um webhook é desabilitado. Se isso acontecer, certifique-se de gastar algum tempo solucionando problemas, corrigindo e testando o webhook antes de reabilitá-lo. É importante que a API que recebe um webhook seja capaz de lidar com o volume de eventos que é produzido por envios de mensagens. Revisar o volume de envios de mensagens produzidos pelo seu aplicativo refletirá o desempenho necessário da sua API.

​
Orientação de desempenho

  • Endpoints lentos ou sobrecarregados (especialmente com respostas 429) podem acionar a desabilitação.
  • APIs devem registrar eventos rapidamente e adiar processamento adicional para evitar timeouts.
  • O volume escala com a atividade do usuário—certifique-se de que seu endpoint pode lidar com essa taxa de transferência.
  • Use o valor event.id (disponível como cabeçalho ou no corpo) para deduplicar eventos recebidos.

​
Dicas para o sucesso

  • Conecte webhooks aos seus próprios servidores primeiro, não diretamente a serviços de terceiros.
    • Embora webhooks do OneSignal possam chamar qualquer API pública, rotear através do seu próprio servidor dá mais controle.
    • É mais fácil fazer debug, adicionar logging, lidar com autenticação e limitar ou enfileirar requisições conforme necessário.
    • Serviços de terceiros podem limitar taxa ou bloquear requisições se o volume aumentar, e o OneSignal não gerencia esses limites.
  • A execução de webhook acontece imediatamente quando os usuários alcançam essa etapa na Journey.
    • Se muitos usuários atingirem uma etapa de webhook de uma vez, o OneSignal enviará uma rajada de requisições HTTP sem limitação de taxa.
    • Isso pode facilmente sobrecarregar serviços externos, acionar limites de taxa ou incorrer em cobranças inesperadas.
    • Considere construir uma camada de API leve ou proxy de enfileiramento que possa:
      • Receber webhooks de forma confiável
      • Aplicar limites de taxa ou lotes
      • Rotear requisições para seus serviços de terceiros graciosamente
  • Use APIs de terceiros com cuidado:
    • A maioria das ferramentas populares (por exemplo, Slack, Twilio, Segment) oferece APIs HTTP públicas.
    • Revise seus limites de taxa, requisitos de autenticação e estratégias de tratamento de erros.
    • Procure exemplos de código em suas documentações para ver como sua requisição de webhook deve parecer.

​
Protegendo seu webhook

Para garantir que as requisições estão vindo do OneSignal e não foram adulteradas:
  • Use um cabeçalho de assinatura HMAC com um segredo compartilhado
  • Adicione um token de autenticação personalizado no cabeçalho e verifique-o no lado do servidor