Integração de webhooks de entrada

Necessária a ajuda do desenvolvedor

Você precisará da ajuda de sua equipe de desenvolvimento para configurar a integração. Por favor, compartilhe este guia com eles.

Webhooks de entrada permitem que serviços de terceiros enviem eventos diretamente para o Pushwoosh. Quando um serviço de terceiros aciona um webhook, o Pushwoosh autentica a solicitação, identifica o usuário e aplica o mapeamento que você configurou: preenche tags no perfil do usuário, dispara um evento Pushwoosh, ou ambos. Um evento disparado pode então iniciar ou avançar uma jornada.

Use webhooks de entrada para conectar ferramentas como CRMs, plataformas de e-commerce ou serviços de análise sem construir ou manter seu próprio servidor.

Se o identificador de entrada não corresponder a um usuário existente, o Pushwoosh pode criar o usuário em vez de descartar a solicitação. Ative a caixa de seleção de criação automática descrita em Mapear dados de entrada.

Antes de começar

Prepare o seguinte antes de abrir a configuração do webhook.

1. Decida o que o webhook deve fazer. Um webhook deve mapear pelo menos uma tag, um evento, ou ambos. Para disparar um evento, escolha um existente em seu projeto (por exemplo, CheckoutSuccess) ou crie um com os atributos que você deseja preencher a partir dos dados de entrada. As tags podem ser mapeadas para tags existentes ou criadas no momento da configuração do webhook.

2. Certifique-se de que seu serviço de terceiros pode enviar webhooks. O serviço deve ser capaz de enviar uma solicitação HTTP POST para uma URL externa quando o evento de seu interesse ocorrer, por exemplo, um novo pedido ou o envio de um formulário.

3. Obtenha um payload JSON de amostra do seu serviço de terceiros. Este é um pequeno exemplo dos dados que o serviço envia em cada evento. Você precisará dele para mapear os campos do payload para as tags e atributos do evento.

Criar um webhook

Abrir a configuração do webhook

1. Na sua conta Pushwoosh, vá para Configurações → Integrações → Webhooks de entrada e clique em Configurações.

2. Clique em Criar webhook para abrir a tela de configuração: Cole um payload de amostra à esquerda, Configuração do webhook à direita.

3. Insira um nome para o webhook para que você possa identificá-lo na lista mais tarde.

Mapear dados de entrada

1. Em Cole um payload de amostra, cole um payload JSON de amostra do seu serviço de terceiros. O Pushwoosh extrai os campos e os carrega nos menus suspensos de campos de payload.

Nota

Se você atualizar o payload mais tarde, clique em Recarregar opções de seleção para atualizar os menus suspensos. Isso redefinirá seu mapeamento de campo atual. Você precisará remapear seus campos.

Payload de amostra:

{
  "id": "12345",
  "email": "jane@example.com",
  "phone": "+15551234567",
  "loyalty_tier": "gold",
  "order_number": "ORD-001",
  "price": 99.99
}

2. Em Identificar usuários por, escolha como o Pushwoosh deve corresponder a solicitação de entrada a um usuário:

• ID do Usuário: seu identificador interno atribuído a um usuário no sistema.
• E-mail: corresponde por endereço de e-mail.
• Telefone: corresponde por número de telefone.
• HWID: um identificador de dispositivo, navegador ou e-mail.
• Token: corresponde por um token de push de dispositivo.

3. Em Campo do payload, selecione o campo que contém o valor correspondente.

4. Opcional: ative a caixa de seleção abaixo de Campo do payload para criar um novo usuário automaticamente quando nenhuma correspondência for encontrada, em vez de descartar a solicitação. O rótulo corresponde à sua escolha de identificador, por exemplo, Criar um novo ID de Usuário se nenhuma correspondência for encontrada ou Criar um novo E-mail se nenhuma correspondência for encontrada. A caixa de seleção está desativada para HWID e Token, porque o Pushwoosh não pode criar um identificador de dispositivo, navegador ou token de push antes de uma sessão real do SDK.

Cada webhook deve mapear pelo menos uma tag, disparar um evento, ou ambos.

Adicionar tags ao perfil

Use Adicionar tags ao perfil para salvar valores do payload como tags no perfil do usuário correspondente. Preencha dados do perfil como nível do plano ou cidade para uma melhor segmentação.

1. Clique em + Adicionar tag.
2. Em Nome da tag, escolha uma tag existente na lista ou digite um novo nome. O Pushwoosh exibe Criar: <name> para confirmar que criará uma.
3. Se você escolheu uma tag existente, o Tipo mostra seu tipo e não pode ser alterado. Se você criou uma nova tag, abra o Tipo e escolha seu tipo de dados. O Pushwoosh a salva como uma tag específica do usuário deste tipo.
4. Em Campo do payload, selecione o campo do seu payload de amostra que contém o valor.
5. Repita os passos 1 a 4 para cada tag que você deseja preencher.

Para remover uma linha, clique em ×.

Registrar um evento

Use Registrar um evento para disparar um evento Pushwoosh quando o webhook receber uma solicitação válida. Um evento disparado pode iniciar ou avançar uma jornada.

1. Em Evento, selecione o evento Pushwoosh a ser disparado.
2. Clique em + Adicionar atributo.
3. Em Atributo do evento, escolha um atributo existente do evento selecionado na lista ou digite um novo nome. O Pushwoosh exibe Criar: <name> para confirmar que criará um.
4. Se você escolheu um atributo existente, o Tipo mostra seu tipo e não pode ser alterado. Se você criou um novo atributo, abra o Tipo e escolha seu tipo de dados.
5. Em Campo do payload, selecione o campo do seu payload de amostra que contém o valor.
6. Repita os passos 2 a 5 para cada atributo que você deseja preencher.

Para remover uma linha, clique em ×.

Habilitar e conectar

1. Quando a configuração estiver concluída, clique em Habilitar webhook. A janela URL do Webhook será aberta.

Necessária a ajuda do desenvolvedor

Os próximos passos exigem acesso às configurações de webhook do seu serviço de terceiros. Compartilhe a URL e o Segredo com sua equipe de desenvolvimento.

2. Copie a URL e defina-a como o destino do webhook em seu serviço de terceiros.

3. Copie o Segredo e cole-o em seu serviço de terceiros como o valor do cabeçalho Authorization. O valor inclui o prefixo Bearer, então use-o como está. O Pushwoosh rejeita qualquer solicitação em que este cabeçalho esteja ausente ou não corresponda.

4. Clique em Copiar no bloco Solicitação de exemplo para copiar uma solicitação POST de amostra. Use-a para enviar uma solicitação de teste e confirmar que o Pushwoosh aceita o webhook, ou compartilhe-a com sua equipe como um modelo para a integração.

Depois de habilitar o webhook, ele aparece na lista de Webhooks com o status habilitado e começa a aceitar solicitações.

Lista de webhooks

A lista de webhooks de entrada mostra todos os webhooks em seu projeto.

Cada linha mostra:

• Nome: nome do webhook.
• Status: Habilitado ou Desabilitado.
• Recebidas: número total de solicitações de entrada recebidas pelo webhook.
• Última modificação: quando o webhook foi alterado pela última vez.

Gerenciar webhooks

Abra o menu da linha para:

• Editar configurações: abre a configuração do webhook para que você possa alterar o nome, evento, mapeamento de campos e identificação do usuário.
• Copiar URL: abre a janela URL do Webhook com a URL e o Segredo para que você possa copiá-los novamente.
• Registro de atividades: abre o registro de solicitações para este webhook.
• Excluir: remove o webhook da lista.

Para um webhook habilitado, clique em Desabilitar para desativá-lo sem excluir a configuração. Para um webhook desabilitado, clique em Habilitar para começar a aceitar solicitações novamente.

Visualizar o registro de atividades

O registro de atividades mostra todas as solicitações de entrada para o webhook selecionado.

Painel de resumo

No topo, revise o resumo das últimas 24 horas:

• Total de acessos: número total de solicitações de entrada recebidas.
• Aviso: solicitações em que o usuário foi identificado (ou criado), mas pelo menos um mapeamento de tag ou evento configurado falhou ao ser aplicado.
• Falha: solicitações que não foram processadas, por exemplo, devido a um segredo incorreto ou a um campo de identificador ausente. Uma solicitação com falha não interrompe o webhook. O Pushwoosh continua a aceitar e processar solicitações posteriores.

Motivo da falha	O que significa
Autenticação rejeitada	O segredo compartilhado não corresponde à configuração do webhook. Se cinco solicitações consecutivas falharem com este erro, o Pushwoosh enviará uma notificação. Atualize o segredo para continuar. Nenhuma reativação é necessária.
Campo identificador do usuário ausente	O campo do payload mapeado para a identificação do usuário não está presente na solicitação.

Entradas de solicitação

Cada entrada mostra um ícone de status, o identificador do usuário (por exemplo, ID do Usuário ou E-mail), o carimbo de data/hora da solicitação e uma marca de verificação para cada capacidade que você configurou no webhook: ID do Usuário (ou seu identificador escolhido), Tags e Evento. Uma marca de verificação significa que parte da solicitação foi aplicada com sucesso; uma solicitação pode mostrar uma mistura de itens verificados e com falha. Clique em Mostrar para expandir o payload JSON completo recebido.

Visualizar eventos e tags disparados por webhook no User Explorer

Quando uma solicitação de webhook é processada com sucesso, o Pushwoosh registra o resultado no usuário correspondente (ou recém-criado) no User Explorer. Onde o evento aparece depende de como você identificou o usuário:

• ID do Usuário, E-mail ou Telefone: o evento é registrado no perfil do usuário. Abra o usuário e vá para o Histórico de eventos.
• HWID: o evento é registrado no dispositivo correspondente. Abra o usuário, encontre o dispositivo em Dispositivos de usuário ativos e vá para a aba Histórico de eventos.

Encontre o evento pelo nome e expanda-o para ver os atributos mapeados (por exemplo, price ou products) e o atributo __webhook com o ID do webhook. As tags mapeadas aparecem no mesmo usuário, na aba Visão geral do usuário, independentemente do tipo de identificador.

Usar webhooks de entrada com jornadas

Depois que um webhook é habilitado e está disparando eventos com sucesso, use o evento selecionado como uma entrada de jornada baseada em gatilho. Quando o webhook recebe uma solicitação válida, o Pushwoosh dispara o evento mapeado. Qualquer jornada que use este evento como um gatilho de entrada é iniciada automaticamente para o usuário correspondente.