Webhook

Assistência de desenvolvedor necessária

Você precisará da ajuda da sua equipe de desenvolvedores para configurar o elemento Webhook. Compartilhe este guia com eles para começar.

Webhooks permitem que você envie dados da jornada para serviços externos, como análises, sistemas de CRM e ferramentas de marketing. Você pode:

• Notificar sistemas externos quando um cliente realiza uma ação na jornada
• Enviar dados do cliente para ferramentas de análise
• Acionar e-mails, SMS ou WhatsApp de terceiros em eventos específicos da jornada

Nota

Confira alguns exemplos de como implementar webhooks para diferentes casos de uso e serviços: Exemplos de Integração de Webhook

Como configurar o elemento Webhook

Adicionar o elemento Webhook

Arraste e solte o elemento Webhook na tela. Posicione o Webhook onde desejar, levando em consideração quais informações da jornada você enviará para um serviço de terceiros.

Nomeie a etapa do Webhook e especifique a URL e o tipo da solicitação

No campo NOME DA ETAPA, insira um nome para o webhook. Pode ser útil nomear os webhooks de acordo com os serviços para os quais eles enviam dados ou o caso de uso.

Em seguida, no campo URL, especifique a URL da solicitação para a qual os dados devem ser enviados. Ao lado do campo URL, selecione o tipo de solicitação no menu suspenso TIPO DE SOLICITAÇÃO: GET ou POST.

Nota

A URL deve ser publicamente acessível. O Pushwoosh rejeita endereços privados, internos, de loopback e link-local, incluindo endpoints de metadados de nuvem, quer eles venham da própria URL ou de um redirecionamento para o qual ela aponta. Consulte Tempo limite, novas tentativas e solicitações com falha para saber o que acontece quando uma solicitação é bloqueada.

Configurar cabeçalhos

Na seção CABEÇALHOS, defina o tipo de conteúdo.

Por padrão, o tipo de conteúdo é application/json. Se o serviço para o qual você está enviando o webhook exigir outro tipo de conteúdo, insira o apropriado no valor do cabeçalho Content-Type.

Exemplos de tipos de conteúdo são:

• x-www-form-urlencoded
• text/plain
• text/xml

Adicione cabeçalhos adicionais, se necessário, clicando em + ADICIONAR CABEÇALHO. Você pode remover qualquer cabeçalho clicando no ícone ‘x’ ao lado dele.

Adicione qualquer cabeçalho de autenticação que seu endpoint exija, por exemplo:

• Authorization: Bearer <token>
• X-Api-Key: <key>
• Authorization: Basic <base64(user:pass)>

Apenas um segredo estático em um cabeçalho é suportado. Fluxos de troca de token OAuth2, mTLS e assinatura de solicitação do lado do Pushwoosh não são suportados. Você também pode restringir o endpoint aos endereços IP do Pushwoosh em vez de, ou além de, um segredo de cabeçalho. Consulte Endereços IP do Pushwoosh.

Nota

Precisa passar um valor por usuário, como um token ou ID, em vez de um segredo fixo? Insira uma macro de Dados Dinâmicos na URL ou no corpo JSON, por exemplo, como um parâmetro de consulta ou um campo de corpo que seu endpoint lê.

Para autenticação HTTP Basic especificamente, faça o seguinte:

1. Abra um editor de texto simples e digite seu nome de usuário e senha sem espaços, separados por dois pontos. Por exemplo: <username>:<password>
2. Codifique esta string em Base64.
3. Copie a string Base64 resultante (por exemplo, <base64-encoded-string>).
4. Nas configurações do webhook, adicione um cabeçalho de Autorização com o valor: Basic <base64-encoded-string>. Certifique-se de que há um espaço após a palavra “Basic”.

Marcar um valor de cabeçalho como secreto

Clique no ícone de olho ao lado do valor de um cabeçalho para mascará-lo. O Pushwoosh oculta esse valor em todos os lugares onde ele sairia do serviço: na interface do usuário, nas respostas da API e no histórico de versões da jornada.

• Mascaramento automático. Cabeçalhos cujos nomes parecem credenciais são mascarados automaticamente, mesmo que você nunca clique no ícone de olho. Isso inclui Authorization, Proxy-Authorization, Cookie, Set-Cookie e qualquer nome que contenha token, secret, password, credential, auth ou api-key/api_key/apikey (com hífen, sublinhado ou sem separador).
• Alterar um valor mascarado. Clique no campo que mostra •••••••• e digite o novo valor. Não há um botão para revelar o valor armazenado. O ícone de olho permanece bloqueado enquanto a máscara é exibida. Para remover a marca de segredo de um cabeçalho, digite um novo valor primeiro e, em seguida, clique no ícone.
• Renomear um cabeçalho mascarado. Renomear um cabeçalho cujo valor é atualmente exibido como a máscara limpa esse valor. Insira-o novamente sob o novo nome. Renomear um cabeçalho que atualmente contém um valor que você acabou de digitar mantém esse valor.

Nota

No histórico de versões da jornada, uma alteração no valor de um cabeçalho secreto mostra a máscara em ambos os lados do diff. Você pode saber que um cabeçalho secreto mudou, mas não de qual valor para qual valor.

Adicionar o corpo da solicitação JSON

Na seção DADOS, insira o corpo da sua solicitação JSON. Certifique-se de que o corpo da solicitação esteja no formato JSON correto.

Nota

Se não houver valor para o placeholder de Dados Dinâmicos quando a solicitação for enviada, o Pushwoosh enviará uma string vazia em seu lugar.

Exemplo:

{
  "hwid": "{{device:hwid}}"
}

Use dados dinâmicos e macros

O painel CONSTRUTOR DE DADOS permite que você insira informações dinâmicas (como dados de usuário, dispositivo, Tag ou evento) diretamente no corpo da sua solicitação JSON. Com os Dados Dinâmicos, você pode incluir valores específicos para o usuário individual que está progredindo na jornada.

Para isso:

1. Selecione uma categoria. Você pode extrair dados de três categorias:

   • Dispositivo: Use dados do Dispositivo quando precisar de informações técnicas vinculadas ao dispositivo do usuário.

   • Tag: Use dados de Tag quando quiser enviar informações armazenadas no perfil do usuário.

   • Evento: Use dados de Evento quando o webhook deve enviar valores do evento que acionou a jornada.

Nota

Os valores do evento de acionamento permanecem anexados ao usuário pelo resto da jornada, inclusive através de um Atraso de Tempo. Eles só são perdidos se o usuário sair da jornada, por exemplo, em um evento de cancelamento, uma saída ou quando a jornada termina. Se um usuário passar pela mesma etapa de Webhook mais de uma vez, a nova resposta substitui o valor que mapeou da última vez.

2. Selecione um parâmetro (por exemplo, HWID, categoria favorita, etc.).
3. O Pushwoosh gera uma macro que se parece com isto:

{{tag:Language}}

4. Copie a macro e cole-a no seu corpo JSON na seção DADOS.

Quando o webhook é executado em uma jornada ativa, o Pushwoosh substitui automaticamente a macro pelo valor real para aquele usuário.

Digite placeholders adicionais manualmente

Um placeholder é uma macro que você digita manualmente em vez de gerá-la a partir de uma categoria do CONSTRUTOR DE DADOS. O painel CONSTRUTOR DE DADOS cobre apenas dados de Dispositivo, Tag e Evento. Digite esses placeholders diretamente nas seções URL, CABEÇALHOS ou DADOS. Eles não aparecem no painel:

Placeholder	Valor
{{application_code}}	O código do aplicativo do aplicativo ao qual o usuário pertence.
{{traveler:id}}	O ID que o Pushwoosh atribui a este usuário para esta execução da jornada.
{{journey:uuid}}	O UUID desta jornada.
{{journey:name}}	O nome desta jornada.
{{point:uuid}}	O UUID desta etapa de Webhook.
{{point:name}}	O NOME DA ETAPA desta etapa de Webhook.
{{event:name}}	O nome do evento que acionou a entrada deste usuário na jornada.
{{device:platform}}	A plataforma do dispositivo, por exemplo, Android ou iOS.
{{device:push_subscribed}}	Se o usuário está inscrito para notificações push — true ou false.
{{now}}	A data e hora atuais, ISO 8601, UTC.
{{now:unix_ms}}	A hora atual como milissegundos Unix.
{{tags:all}}	Todos os valores de tag para o dispositivo do usuário, como um único objeto JSON. Use-o sem aspas, por exemplo, "user_properties": {{tags:all}}. Colocá-lo entre aspas transforma o objeto em uma string com escape.

Nota

Um placeholder com erro de digitação, ou que não está nesta lista ou no CONSTRUTOR DE DADOS, é enviado para o endpoint exatamente como digitado, incluindo as chaves. Não há banner de erro para isso. Verifique o corpo da solicitação no Registro de chamadas se um valor que você esperava estiver faltando.

Mantenha o tipo de um placeholder no corpo JSON

Um placeholder dentro de aspas sempre se torna uma string JSON, qualquer que seja o tipo real do valor. O mesmo placeholder por si só, sem aspas ao redor, mantém o tipo próprio do valor: um número permanece um número, true/false permanece um booleano e uma lista se torna um array JSON. Um placeholder sem aspas deve ser o valor inteiro do campo — "age": {{tag:Age}} funciona, mas "note": prefix{{tag:Age}}suffix não, porque tudo fora das aspas é escrito exatamente como digitado e os caracteres extras quebram o JSON.

{
  "age": {{tag:Age}},
  "age_as_text": "{{tag:Age}}"
}

Aqui, age envia o valor numérico da tag (34), enquanto age_as_text envia a string "34". Use o que o campo no lado receptor espera. Se a tag não tiver valor, um placeholder sem aspas ainda resolve para uma string vazia, não um número ou false. Veja a nota em Adicionar o corpo da solicitação JSON.

Cuidado

Um placeholder de data é renderizado de forma diferente dependendo de onde você o coloca. Entre aspas, ele mantém o formato YYYY-MM-DD HH:MM:SS que as integrações existentes já analisam. Sem aspas, é ISO 8601, por exemplo, 2026-09-15T08:24:00Z. Os dois não são intercambiáveis. Escolha a posição que corresponde ao formato esperado do seu endpoint.

Mapear dados de resposta do webhook para variáveis

Além de enviar dados, a etapa de Webhook pode guardar valores da resposta que seu serviço envia de volta. Você dá a cada valor um nome (Atributo). Etapas posteriores podem usar esse nome da mesma forma que usam outros valores de resposta de webhook. Por exemplo, defina uma Tag com Atualizar perfil do usuário, ou agende um Atraso de Tempo a partir de uma data que o serviço retornou. Para um exemplo completo de jornada, consulte Usando dados de resposta de webhook em sua jornada.

Exemplo: o CRM retorna um ID de usuário. Você o armazena como Atributo crm_user_id. Em seguida, Atualizar perfil do usuário o escreve em uma Tag.

Antes de mapear qualquer coisa, obtenha uma resposta de amostra do serviço. Peça ao seu desenvolvedor, ou abra uma chamada bem-sucedida no Registro de chamadas após um teste e olhe o corpo da resposta. Você precisa dos nomes dos campos dessa resposta para construir o Caminho.

Na seção MAPEAMENTO DA RESPOSTA, clique em + ADICIONAR MAPEAMENTO e preencha dois campos para cada valor que você deseja capturar:

• Caminho: a localização do valor dentro do corpo JSON da resposta, com pontos entre os níveis
• Atributo: o nome que você usará mais tarde na jornada

Por exemplo, se o seu CRM responder com:

{
  "data": {
    "user": {
      "id": "789xyz"
    }
  }
}

1. Defina o Caminho como data.user.id.
2. Defina o Atributo como crm_user_id.

Depois que um usuário passa por esta etapa, elementos posteriores podem escolher o Atributo crm_user_id da mesma forma que escolhem outros valores de resposta de webhook.

A Divisão de condição não pode usá-los diretamente. Os valores de webhook mapeados não têm tipo. Salve o valor como uma Tag primeiro e, em seguida, ramifique com base nessa Tag. Consulte Comparar um valor de webhook na Divisão de condição.

Cuidado

Se a resposta for maior que 64 KB, nada dela é mapeado. Mantenha a resposta que seu endpoint envia de volta razoavelmente pequena se você planeja mapear valores dela.

Para um único campo, o Caminho e os valores funcionam assim:

Nota

• Escreva nomes de objetos com pontos: data.user.id.
• Para uma lista, use um número de posição para pegar um item. O primeiro item é 0, então results.0.code é o campo code do primeiro item. Para mapear cada item em uma lista, consulte Mapear cada elemento de um array.
• Você não pode mapear apenas alguns itens em uma lista. Para uma lista, é ou uma posição ou todos os itens.
• O Pushwoosh mantém o valor como o serviço o enviou (texto, número ou verdadeiro/falso). Um número 100 permanece um número. O texto "100" permanece texto e não funcionará onde a jornada espera um número. Para uma data de Atraso de Tempo, o serviço deve retornar um formato que o Atraso de Tempo aceite. Um decimal como 19.99 pode ir para uma Tag do tipo Preço.
• Se a resposta não for um JSON válido, ou o Caminho não corresponder a nenhum campo, esse atributo não é criado para este usuário. A etapa de Webhook ainda termina como de costume. Não há banner de erro. Verifique o corpo da resposta no Registro de chamadas e corrija o Caminho se o valor estiver faltando mais adiante.

Mapear cada elemento de um array

Às vezes, uma resposta de webhook não tem apenas um valor. Ela tem uma lista, como cada produto em um pedido, cada item em um carrinho ou cada resultado de uma pesquisa. O mapeamento de resposta normalmente captura um valor por campo, então sem isso você só obteria um valor mapeado daquela lista, e o resto seria perdido.

Coloque * no campo Caminho onde a lista está. O Pushwoosh então pega um valor de cada item na lista, não apenas de uma posição. Por exemplo, se a lista se chama items e cada item tem item_name, defina o Caminho como items.*.item_name.

Em MAPEAMENTO DA RESPOSTA, clique em + ADICIONAR MAPEAMENTO e preencha os dois campos como de costume, com * marcando a lista:

• Caminho: a localização do valor dentro da resposta, com * onde a lista está. Exemplo: items.*.item_name.
• Atributo: o nome que você usará mais tarde. O que você escreve aqui decide como você obterá os resultados de volta:
  • Inclua {n} no nome, por exemplo, item_{n}, para obter cada item como seu próprio valor, numerado a partir de 1: item_1, item_2, item_3 e assim por diante. {n} pode estar em qualquer lugar no nome, por exemplo, item_{n}_sku.
  • Deixe {n} de fora, por exemplo, item_names, para juntar cada item em um único valor, separado por vírgulas: Sofá, Luminária, Tapete.

As posições da lista no Caminho começam em 0 (items.0.item_name é o primeiro item). Os nomes de Atributo construídos com {n} começam em 1 (item_1 é esse primeiro item). São duas numerações diferentes.

Se você precisar de apenas um item da lista, use um número no Caminho em vez de *, por exemplo, items.0.item_name.

Exemplo

Se o seu CRM responder com:

{
  "items": [
    { "item_name": "Sofa" },
    { "item_name": "Lamp" },
    { "item_name": "Rug" }
  ]
}

• Defina o Caminho como items.*.item_name e o Atributo como item_{n} para obter três valores separados: item_1 é Sofa, item_2 é Lamp, item_3 é Rug.
• Defina o Atributo como item_names para obter um único valor: item_names é Sofa, Lamp, Rug.

Nota

Se um item na lista estiver faltando o campo que você está procurando (por exemplo, sem item_name), esse item é pulado. A numeração não deixa uma lacuna para ele. Exemplo: três linhas onde a do meio não tem item_name se tornam apenas item_1 e item_2.

Apenas os primeiros 50 itens em uma lista são capturados. Qualquer coisa além disso é descartada. O usuário ainda continua na jornada. Apenas os valores não mapeados estão faltando.

Você pode usar os valores mapeados mais tarde na jornada como qualquer outro atributo de resposta de webhook:

• Atualizar perfil do usuário: salvar um valor em uma Tag
• Atraso de Tempo: esperar até uma data da resposta
• Conteúdo Dinâmico: personalizar o conteúdo da mensagem

A Divisão de condição não pode usá-los diretamente. Os valores de webhook mapeados não têm tipo. Salve o valor como uma Tag primeiro e, em seguida, ramifique com base nessa Tag. Consulte Comparar um valor de webhook na Divisão de condição.

Usando dados de resposta de webhook em sua jornada

Tempo limite, novas tentativas e solicitações com falha

O Pushwoosh espera até 10 segundos por uma resposta. Toda a etapa de Webhook, incluindo o envio da solicitação e o processamento da resposta, tem um limite de 30 segundos.

Novas tentativas

Em uma resposta 500, 502, 503 ou 504, ou um erro de rede como uma falha de conexão, o Pushwoosh tenta novamente a solicitação uma vez antes de desistir. Uma solicitação que expira não é tentada novamente — veja O que acontece quando uma solicitação falha abaixo. Qualquer outra resposta que não seja 2xx também não é tentada novamente.

Nota

Uma nova tentativa reenvia exatamente a mesma solicitação. Torne seu endpoint seguro para receber a mesma chamada duas vezes (idempotente) se uma duplicata for um problema, por exemplo, cobrar um pagamento ou criar um registro duas vezes.

Limites de taxa

O Pushwoosh limita quantas solicitações de webhook uma conta pode enviar por segundo. O limite é dimensionado bem acima dos picos de tráfego real, então as jornadas normais não são afetadas. Uma rajada que o excede espera brevemente por espaço antes de falhar.

Cooldown do endpoint

Se um endpoint falhar várias vezes seguidas, o Pushwoosh para de enviar solicitações a ele por um tempo, em vez de tentar novamente um endpoint quebrado a cada usuário, começando em 30 segundos e dobrando em falhas futuras até 5 minutos. Uma única solicitação bem-sucedida limpa isso e retoma a entrega normal.

O que acontece quando uma solicitação falha

O elemento Webhook não tem um ramo separado para solicitações com falha. Qualquer um dos seguintes itens remove o usuário da jornada nesta etapa:

Causa	O que a aciona
Endereço de endpoint bloqueado	A URL é privada, interna, de loopback ou link-local, incluindo endpoints de metadados de nuvem
Limite de taxa	O limite de solicitações de webhook por segundo da conta é excedido e nenhum espaço se abre durante a breve espera
Cooldown do endpoint	O endpoint falhou várias vezes seguidas e o Pushwoosh está temporariamente pulando-o
Tempo limite	Nenhuma resposta em 10 segundos, ou a etapa excede seu limite de 30 segundos
Erro de rede	A solicitação não conseguiu alcançar o endpoint de forma alguma
Resposta não-2xx	O endpoint retornou um status de erro que não é tentado novamente, ou foi tentado novamente uma vez e falhou novamente

Consulte Erro de solicitação.

Se você não pode perder usuários aqui, faça com que seu endpoint sempre retorne uma resposta 2xx e coloque qualquer estado de falha no corpo da resposta, por exemplo, como um valor que seu Mapeamento de resposta possa capturar.

Isso se aplica a cada etapa de Webhook, incluindo as criadas anteriormente. Um endereço de endpoint que agora corresponde à regra de endereço bloqueado acima começará a falhar da mesma maneira.

Ao contrário de uma solicitação com falha, uma resposta que chega, mas não é mapeada corretamente, como JSON inválido, um Caminho não resolvido ou um corpo com mais de 64 KB, não remove o usuário. Veja a nota em Mapeamento de resposta acima.

Testar o Webhook

Clique em Testar webhook para verificar se a configuração do seu webhook está correta e se a solicitação é enviada com sucesso.

Se um cabeçalho ainda mostrar a máscara armazenada, o Pushwoosh preenche o valor real salvo para a solicitação de teste. O valor nunca aparece no seu navegador.

Essa substituição só funciona para um cabeçalho já salvo nesta etapa exata. Uma etapa que você ainda não salvou, ou uma que você acabou de copiar, não tem valor salvo por trás da máscara, então o Pushwoosh envia a solicitação de teste sem esse cabeçalho.

Após um teste bem-sucedido (ou uma chamada ao vivo), abra o Registro de chamadas, expanda a linha e compare o corpo da resposta com cada Caminho. O campo deve existir exatamente como no Caminho. Se a solicitação for bem-sucedida, mas uma etapa posterior não tiver valor, o Caminho geralmente não corresponde à resposta. A etapa de Webhook não mostrará um erro para isso.

Salvar sua configuração

Clique em Salvar para salvar a configuração do seu webhook.

Registro de chamadas

Abra a aba Registro de chamadas na gaveta do ponto para ver o que o Pushwoosh realmente enviou para esta etapa: hora, usuário, resultado e duração, retrocedendo 30 dias.

Nota

O Registro de chamadas registra apenas as solicitações que o Pushwoosh realmente enviou. Um usuário removido antes desse ponto, por exemplo, pelo limite de taxa ou um cooldown do endpoint, não terá uma linha aqui.

Filtre por resultado (Sucesso, Erro HTTP, Sem resposta) ou pesquise pelo User ID ou HWID exato. Clique em uma linha para expandi-la e ver a solicitação (método, URL e corpo) e, dependendo do resultado, a resposta (status e corpo) ou o texto do erro. A Duração cobre toda a etapa, incluindo o tempo gasto em uma nova tentativa automática.

Cuidado

Corpos de solicitação e resposta com mais de 4 KB são cortados, marcados com …[truncated]. Qualquer valor que o Pushwoosh enviou em um cabeçalho, como um token de portador ou chave de API, é substituído por [redacted] em todos os lugares onde apareceria: na URL, nos corpos e no texto do erro, não apenas em um campo de cabeçalhos.