Integração de webhook de entrada

Webhooks de entrada permitem que serviços externos enviem eventos diretamente para o Pushwoosh. Quando um sistema de terceiros aciona um webhook, o Pushwoosh autentica a solicitação, identifica o assinante e dispara o evento mapeado. O evento 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. Cada webhook de entrada aciona um evento do Pushwoosh quando uma solicitação correspondente é recebida e processada com sucesso.

Antes de começar

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

Decida qual evento do Pushwoosh o webhook deve acionar. Escolha um evento existente do seu projeto que você deseja acionar a partir do serviço de terceiros. Por exemplo, CheckoutSuccess. Se você ainda não tiver um evento adequado, crie um com os atributos que deseja preencher a partir dos dados recebidos.
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.
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 os atributos do evento do Pushwoosh.

Criar um webhook

Na sua conta Pushwoosh, vá para Settings → Integrations → Inbound webhooks e clique em Settings.

Página de integrações com o cartão de Webhooks de entrada e o botão Configurações para abrir a configuração do webhook

Clique em Create webhook para abrir o fluxo de configuração.

Tela de criação de webhook com nome, evento, payload de amostra e mapeamento de identificador de usuário

Insira um nome para o webhook para que você possa identificá-lo na lista mais tarde.
Selecione o evento do Pushwoosh que deve ser acionado quando o webhook receber uma solicitação válida. Você pode escolher entre os eventos que já existem no seu projeto. Se precisar criar um evento primeiro, consulte Eventos.

Tela de configuração de webhook com menu suspenso de eventos do Pushwoosh para selecionar o evento a ser acionado na solicitação de entrada

Em Match incoming data, cole um payload JSON de amostra do seu serviço de terceiros. O Pushwoosh carrega os campos do payload nos menus suspensos automaticamente.

Payload de amostra:

{
  "user_id": "12345",
  "email_address": "jane@example.com",
  "mobile": "+15551234567",
  "purchase_date": "2024-03-15",
  "order_number": "ORD-001",
  "price": 99.99,
  "payment_state": "success"
}

Em Identify users by, selecione como o Pushwoosh deve corresponder a solicitação recebida a um usuário:

User ID: corresponde pelo ID de usuário interno no Pushwoosh.
Email: corresponde pelo endereço de e-mail.
Phone: corresponde pelo número de telefone.
HWID: corresponde pelo identificador de dispositivo, navegador ou e-mail.

Em Payload field, selecione o campo que contém o valor correspondente.

Menus suspensos Identificar usuários por e Campo do payload com dica de ferramenta de ID do Usuário e HWID na tela de Correspondência de dados de entrada

Mapeie cada atributo de evento para um campo de payload. Em cada linha de mapeamento:

Event attribute: o nome do atributo no Pushwoosh. Selecione a partir dos atributos definidos para este evento.
Payload field: o campo do payload de entrada que contém o valor.

Por exemplo, mapeie email para email_address, total para price e order_id para order_number.

Linhas de mapeamento de atributo de evento e campo de payload com payload de amostra e botão Recarregar opções de seleção

Clique em + Add attribute para adicionar uma linha. Clique em × para remover uma.

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

Copie os valores e cole-os nas configurações de webhook do seu sistema externo:

Copie a URL e defina-a como o destino do webhook em seu serviço de terceiros.
Copie o Secret e cole-o em seu serviço externo 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.

Janela de URL do webhook mostrando os campos URL e Secret com botões de cópia para configuração do sistema externo

A janela também mostra uma Example request com uma solicitação POST de amostra. Clique em Copy no bloco de exemplo para copiar a solicitação completa. 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.

Janela de URL do webhook com URL, Secret e comando curl de Solicitação de exemplo para configuração do sistema externo

Depois de habilitar o webhook, ele aparece na lista de Webhooks com um 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:

Name: nome do webhook.
Event: o evento do Pushwoosh que é acionado quando o webhook recebe uma solicitação válida.
Status: Enabled ou Disabled.
Received: número de solicitações recebidas pelo webhook.
Last updated: quando o webhook foi alterado pela última vez.

Lista de webhooks de entrada com pesquisa, filtros de status, colunas da tabela e menu de ação de linha aberto

Gerenciar webhooks

Abra o menu da linha para:

Edit settings: abre a configuração do webhook para que você possa alterar o nome, evento, mapeamento de campo e identificação do usuário.
Copy URL: abre a janela Webhook URL com a URL e o Secret para que você possa copiá-los novamente.
Activity log: abre o registro de solicitações para este webhook.
Delete: remove o webhook da lista.

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

Visualizar o registro de atividades

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

Painel de resumo

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

Hits: número total de solicitações recebidas.
Success: solicitações em que a autenticação foi aprovada, o usuário foi encontrado e o evento foi acionado.
Failed: solicitações que não foram processadas. 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
Auth rejected	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.
User identifier field missing	O campo de payload mapeado para identificação do usuário não está presente na solicitação.

Entradas de solicitação

Cada entrada mostra o identificador do usuário (por exemplo, User ID ou Email), um selo de Success ou Failed, o carimbo de data/hora da solicitação e uma prévia do payload JSON recebido. Clique em Show para expandir os detalhes completos da solicitação.

Entrada de solicitação do registro de atividades com identificador de usuário, selo de Sucesso ou Falha, carimbo de data/hora, payload JSON e botão Mostrar

Visualizar eventos acionados por webhook no User Explorer

Quando uma solicitação de webhook é processada com sucesso, o Pushwoosh registra o evento no User Explorer. Onde ele aparece depende de como você identificou o usuário:

User ID, Email ou Phone: o evento é registrado no perfil do usuário. Abra o usuário e vá para Events history.
HWID: o evento é registrado no dispositivo correspondente. Abra o usuário, encontre o dispositivo em Active user devices e vá para a guia Events history.

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.

Guia de histórico de eventos do User Explorer mostrando evento de webhook de entrada com atributos expandidos, incluindo ID __webhook e campos de payload mapeados

Usar webhooks de entrada com jornadas

Depois que um webhook é habilitado e está acionando 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 aciona o evento mapeado. Qualquer jornada que use este evento como um gatilho de entrada é iniciada automaticamente para o usuário correspondente.