Criar uma campanha de webhook

Criar uma campanha de webhook ou incluir um webhook em uma campanha multicanal permite acionar ações fora do app, fornecendo informações em tempo real a outros sistemas e aplicativos.

Você pode usar webhooks para enviar informações a sistemas como Salesforce ou Marketo, ou aos seus sistemas de backend. Por exemplo, você pode querer creditar as contas dos seus clientes com uma promoção depois que eles realizarem um evento personalizado um determinado número de vezes.

Dica

Para saber mais sobre o que são webhooks e como você pode usá-los na Braze, confira Webhooks antes de prosseguir.

Etapa 1: Escolha onde criar sua mensagem

Não sabe se sua mensagem deve ser enviada usando uma Campaign ou um Canvas? Campaigns são melhores para campanhas de mensagens únicas e direcionadas, enquanto Canvas são melhores para jornadas de usuário com várias etapas.

• campaign
• canvas

Etapas:

1. Acesse Envio de mensagens > Campaigns e selecione Criar Campaign.
2. Selecione Webhook ou, para campanhas direcionadas a vários canais, selecione Multicanal.
3. Dê à sua campanha um nome claro e significativo.
4. (Opcional) Adicione uma descrição para descrever como essa campanha será usada.
5. Adicione equipes e tags conforme necessário.
   • As tags facilitam a localização das suas campanhas e a criação de relatórios. Por exemplo, ao usar o Construtor de relatórios, você pode filtrar por tags específicas.
6. Adicione e nomeie quantas variantes forem necessárias para sua campanha. Você pode escolher diferentes modelos de webhook para cada uma das variantes adicionadas. Para saber mais sobre esse tópico, consulte Testes multivariantes e A/B.

Dica

Se todas as mensagens da sua campanha forem semelhantes ou tiverem o mesmo conteúdo, crie sua mensagem antes de adicionar variantes adicionais. Em seguida, você pode escolher Copiar da variante no menu suspenso Adicionar variante.

Etapas:

1. Crie seu Canvas usando o criador de Canvas.
2. Depois de configurar seu Canvas, adicione uma etapa no construtor de Canvas. Dê à sua etapa um nome claro e significativo.
3. Escolha um cronograma de etapa e especifique um delay conforme necessário.
4. Filtre seu público para esta etapa conforme necessário. Você pode refinar ainda mais os destinatários desta etapa especificando Segments e adicionando filtros adicionais. As opções de público serão verificadas após o delay, no momento em que as mensagens forem enviadas.
5. Escolha seu comportamento de avanço.
6. Escolha quaisquer outros canais de envio de mensagens que você deseja combinar com sua mensagem.

Etapa 2: Criar seu webhook

Você pode criar um webhook do zero, usar um modelo existente ou usar um dos nossos modelos prontos. Em seguida, crie seu webhook na guia Criar do editor.

A guia Criar consiste nos seguintes campos:

• Idiomas
• URL do webhook
• Método HTTP
• Corpo da solicitação

Idiomas

Você pode enviar um webhook para usuários em vários mercados usando mensagens multilíngues. A tradução é suportada no corpo da solicitação e na URL do webhook.

Para localizar um webhook:

1. Crie os locais que deseja suportar no seu espaço de trabalho.
2. Na guia Criar, envolva apenas o texto que deseja traduzir com tags de tradução. Por exemplo, {% translation greeting %}Hello!{% endtranslation %}.
3. Selecione Gerenciar idiomas, escolha seus locais e adicione traduções fazendo upload de um CSV ou usando a API de traduções.
4. Selecione Usuário multilíngue no menu suspenso Prévia como usuário para visualizar cada local antes do envio.

Importante

Envolva apenas valores legíveis por humanos em tags de tradução. Nunca chaves JSON, colchetes, vírgulas ou outras estruturas. Tradutores podem alterar ou remover caracteres especiais, o que pode produzir um corpo de solicitação malformado que seu endpoint rejeitará.

Para um corpo de solicitação criado com pares de chave-valor JSON, aplique a tag apenas no valor:

1
2
3

{
  "message_body": "{% translation order_ready %}Your order just arrived!{% endtranslation %}"
}

Localizar a URL

Se o seu endpoint difere por mercado, você pode envolver parte da URL em tags de tradução. Mantenha o protocolo (https://) fora das tags e não inclua parâmetros de consulta dentro delas. Para mais detalhes, consulte Localizar URLs.

Modelos de webhook

Os modelos de webhook suportam traduções salvas, então você pode localizar um modelo uma vez e reutilizá-lo em Campaigns e etapas do Canvas. Você precisa da permissão Edit Webhook Templates para adicionar locais e traduções a um modelo. Consulte Modelos de webhook.

URL do webhook

A URL do webhook, ou URL HTTP, especifica seu endpoint. O endpoint é o local para onde você enviará as informações capturadas no webhook.

Se você deseja enviar informações para um fornecedor, o fornecedor deve fornecer essa URL na documentação da API. Se você está enviando informações para seus próprios sistemas, consulte sua equipe de desenvolvimento ou engenharia para confirmar que está usando a URL correta.

A Braze permite apenas URLs que se comunicam pelas portas padrão 80 (HTTP) e 443 (HTTPS).

Usando Liquid

Você pode personalizar as URLs dos seus webhooks usando Liquid. Às vezes, certos endpoints podem exigir que você identifique um usuário ou forneça informações específicas do usuário como parte da URL. Ao usar Liquid, certifique-se de incluir um valor padrão para cada informação específica do usuário que você usar na URL.

Método HTTP

O método HTTP que você deve usar varia dependendo do endpoint para o qual está enviando informações. Na maioria dos casos, você usará POST.

Corpo da solicitação

O corpo da solicitação é a informação que será enviada para a URL que você especificou. Você pode criar o corpo da solicitação do webhook com pares de chave-valor JSON ou texto bruto.

Pares de chave-valor JSON

Os pares de chave-valor JSON permitem que você escreva facilmente uma solicitação para um endpoint que espera um formato JSON. Você só pode usar isso com um endpoint que espera uma solicitação JSON. Por exemplo, se sua chave for message_body, o valor correspondente pode ser Your order just arrived!. Depois de inserir seu par de chave-valor, o criador configurará sua solicitação na sintaxe JSON, e uma prévia da sua solicitação JSON será populada automaticamente.

Você pode personalizar seus pares de chave-valor usando Liquid, como incluir qualquer atributo de usuário, atributo personalizado ou propriedade de evento na sua solicitação. Por exemplo, você pode incluir o nome e o e-mail de um cliente na sua solicitação. Certifique-se de incluir um valor padrão para cada atributo.

Texto bruto

A opção de texto bruto oferece flexibilidade para escrever uma solicitação para um endpoint que espera um corpo em qualquer formato. Por exemplo, você pode usar isso para escrever uma solicitação para um endpoint que espera que sua solicitação esteja em formato XML.

Tanto a personalização quanto as tags de tradução são suportadas em texto bruto.

Se você definir o cabeçalho da solicitação Content-Type como application/x-www-form-url-encoded, o corpo da solicitação deve ser formatado como uma string codificada em URL. Por exemplo:

1

to={{custom_attribute.${example}}}&text=Your+order+just+arrived

Etapa 3: Definir configurações adicionais

Cabeçalhos da solicitação (opcional)

Determinados endpoints podem exigir que você inclua cabeçalhos na sua solicitação. Na seção Compose do criador, você pode adicionar quantos cabeçalhos forem necessários.

Os cabeçalhos de solicitação mais comuns são as especificações de Content-Type (que descrevem o tipo de dados esperado no corpo, como XML ou JSON) e os cabeçalhos de Authorization, que contêm suas credenciais junto ao seu fornecedor ou sistema.

Nota

Os nomes de cabeçalhos HTTP não diferenciam maiúsculas de minúsculas, conforme a RFC 7230, seção 3.2 (“Each header field consists of a case-insensitive field name”). Se o endpoint receptor ou qualquer serviço intermediário (como CDNs) transformar a capitalização do cabeçalho, isso não afetará o processamento — Content-Type, content-type e CONTENT-TYPE são todos tratados de forma idêntica.

As especificações de tipo de conteúdo devem usar a chave Content-Type. Os valores mais comuns são application/json ou application/x-www-form-urlencoded.

Os cabeçalhos de autorização devem usar a chave Authorization. Os valores mais comuns são Bearer {{YOUR_TOKEN}} ou Basic {{YOUR_TOKEN}} , em que YOUR_TOKEN são as credenciais fornecidas pelo seu fornecedor ou sistema.

Etapa 4: Faça um envio de teste da sua mensagem

Antes de colocar sua campanha no ar, a Braze recomenda que você teste o webhook para verificar se a solicitação está formatada corretamente.

Para isso, mude para a guia Teste e envie um webhook de teste. Você pode testar o webhook como um usuário aleatório, um usuário específico (inserindo o endereço de e-mail ou o ID de usuário externo) ou um usuário personalizado com os atributos que desejar.

Após enviar o webhook de teste, uma caixa de diálogo aparecerá com a mensagem de resposta. Se a solicitação do webhook não for bem-sucedida, consulte a mensagem de erro para obter ajuda na solução de problemas do seu webhook. O exemplo a seguir detalha a resposta de um webhook com uma URL de webhook inválida.

1
2
3
4
5
6
7
8
9

404 Not Found

{
  "error": {
    "message": "Unrecognized request URL. Please see https://lob.com/docs or email us at [email protected].",
    "status_code": 404
  }
}

Para saber mais, consulte Enviar mensagens de teste.

Etapa 5: Construa o restante da sua campanha ou Canvas

• campaign
• canvas

Em seguida, construa o restante da sua campanha. Consulte as seções a seguir para mais detalhes sobre como usar nossas ferramentas para criar webhooks.

Escolha o cronograma de entrega ou o disparo

Os webhooks podem ser entregues com base em um horário agendado, uma ação ou um disparo de API. Para saber mais, consulte Agendando sua campanha.

Para entrega baseada em ação, você também pode definir a duração da campanha e o horário de silêncio.

Nesta etapa, você também pode especificar controles de entrega, como permitir que os usuários se tornem reelegíveis para receber a campanha, ou ativar regras de limite de frequência.

Escolha os usuários para direcionar

Em seguida, você deve direcionar os usuários escolhendo segmentos ou filtros para refinar seu público. Nesta etapa, você seleciona o público maior a partir dos seus segmentos e refina ainda mais esse segmento com nossos filtros, se desejar. Você recebe automaticamente uma prévia de como é a população aproximada desse segmento. Lembre-se de que a contagem exata de membros do segmento é sempre calculada antes do envio da mensagem.

Importante

Sua mensagem será enviada apenas para usuários que já atendem às condições que você definiu na etapa Público-alvo. Depois disso, eles ainda precisam atender ao gatilho que você definir na etapa Programar Entrega. Pense no público-alvo como uma sala de espera — apenas as pessoas que já estão dentro podem avançar quando a próxima ação acontecer.

Escolha os eventos de conversão

A Braze permite que você rastreie com que frequência os usuários realizam ações específicas, chamadas eventos de conversão, após receberem uma campanha. Você tem a opção de permitir uma janela de até 30 dias durante a qual uma conversão será contada se o usuário realizar a ação especificada.

Se ainda não tiver feito, conclua as seções restantes da sua etapa do Canvas. Para detalhes sobre como construir o restante do seu Canvas, incluindo testes multivariantes e Otimizar com BrazeAI^TM, consulte Construa seu Canvas.

Etapa 6: Revisar e implantar

Depois de terminar de criar a última parte da sua Campaign ou Canvas, revise os detalhes, teste e envie!

Informações importantes

Erros, lógica de reenvio e tempo limite

Os webhooks dependem de solicitações feitas pelos servidores da Braze a um endpoint externo, e erros podem ocorrer ocasionalmente. Os erros mais comuns incluem erros de sintaxe, chaves de API expiradas, limites de frequência e problemas inesperados no lado do servidor. Antes de enviar uma campanha de webhook:

• Teste seu webhook em busca de erros de sintaxe
• Certifique-se de que as variáveis personalizadas tenham valores padrão

Se o envio do webhook falhar, uma mensagem de erro será registrada no Registro de atividade de mensagens, incluindo detalhes como o timestamp do erro, o nome do app e informações sobre o erro.

Se a mensagem de erro não for suficientemente clara sobre a origem do problema, consulte a documentação do endpoint de API que você está utilizando. Normalmente, essas documentações incluem uma explicação dos códigos de erro do endpoint, bem como suas causas comuns.

Códigos de resposta e lógica de reenvio

Quando a solicitação do webhook é enviada, o servidor receptor retorna um código de resposta indicando o que aconteceu com a solicitação. A tabela a seguir resume as diferentes respostas que o servidor pode enviar, como elas impactam as análises da campanha e se, em caso de erros, a Braze tentará reenviar a campanha:

Nota

A Braze reenvia os códigos de status reenviáveis desta seção por até cinco tentativas no total (a solicitação inicial mais quatro reenvios), com atraso crescente entre as tentativas. Se a Braze não conseguir alcançar seu endpoint, os reenvios podem continuar por até 24 horas.

Cada solicitação de webhook tem um limite de 120 segundos antes de expirar.

Os cabeçalhos de resposta Retry-After e de limite de frequência podem afetar o tempo que a Braze aguarda antes de uma tentativa reenviável (por exemplo, após 408, 429 ou 5XX). Eles não tornam respostas não reenviáveis, como 401, elegíveis para reenvio.

Nota

Se os envios de webhooks parecerem estar ausentes nas análises, abra o Registro de atividade de mensagens da Campaign ou da etapa do Canvas. A Braze reenvia apenas determinadas respostas (por exemplo, 408, 429 e 5XX) — a maioria dos outros erros de cliente 4XX, incluindo 401 Unauthorized, não são reenviados. Para a tabela completa de respostas, consulte Códigos de resposta e lógica de reenvio.

403 Forbidden e lista de IPs permitidos {#403-forbidden-and-ip-allowlisting}

Respostas 403 Forbidden significam que seu endpoint recebeu a solicitação, mas a recusou. As causas comuns incluem autenticação inválida ou ausente, permissões de API insuficientes e regras de rede (como um firewall ou firewall de aplicação web) que bloqueiam os endereços IP de saída da Braze.

Se as solicitações de webhook retornarem consistentemente 403 e seus cabeçalhos de autenticação estiverem corretos, adicione os IPs da Braze para o seu cluster à lista de permissões no servidor que recebe o webhook. Consulte Lista de IPs permitidos. As solicitações de Connected Content usam os mesmos IPs de saída; consulte Lista de IPs permitidos do Connected Content.

Para outros passos de solução de problemas 4XX, consulte Solucionar problemas de webhooks e solicitações de Connected Content.

Autenticação e credenciais de Connected Content

A solicitação HTTP de saída do webhook não suporta o uso de credenciais de Connected Content (:basic_auth ou :auth_credentials) para autenticar no seu endpoint. Em vez disso, configure a autenticação usando Cabeçalhos de solicitação no webhook. Para buscar um token ou segredo no momento do envio, você pode colocar uma tag {% connected_content %} em um campo de cabeçalho ou corpo para que o Liquid a resolva antes do envio do webhook.

Modelos de webhook salvos e uso em Campaigns

A Braze não fornece um relatório integrado que liste todas as Campaigns ou etapas do Canvas que fazem referência a um determinado modelo de webhook salvo. Para auditar o uso, revise as etapas de webhook que utilizam o mesmo URL e método HTTP ou entre em contato com o suporte da Braze.

Solução de problemas e detalhes adicionais de erros

Para explicações detalhadas, passos de solução de problemas e orientações sobre como resolver erros específicos de webhook, consulte Solucionar problemas de webhooks e solicitações de Connected Content. Você também encontrará mais explicações sobre como nosso sistema de detecção de hosts com problemas funciona e como a Braze fornece notificações de erros por meio de e-mails automatizados e registros adicionais no Braze Currents.

Lista de IPs permitidos

Quando um webhook é enviado pela Braze, os servidores da Braze fazem solicitações de rede para os servidores dos nossos clientes ou de terceiros. Com a lista de IPs permitidos, você pode verificar se as solicitações de webhook estão vindo da Braze, adicionando uma camada de segurança.

A Braze enviará webhooks a partir dos seguintes IPs. Os IPs listados são adicionados automática e dinamicamente a qualquer chave de API que tenha sido habilitada para a lista de permissões.

Importante

Se você estiver fazendo um webhook da Braze para a Braze e usando a lista de permissões, deve incluir todos os IPs a seguir, incluindo 127.0.0.1.

• united states (us)
• european union (eu)
• australia (au)
• indonesia (id)
• japan (jp)
• south korea (kr)

Excluir usuários

Para excluir um usuário individual ou um Segment de usuários, acesse Público > Gerenciar público > Excluir usuários. O dashboard suporta exclusão em massa de Segments (até 10 milhões de perfis), inclui uma janela de cancelamento de 7 dias e não consome os limites de frequência compartilhados da REST API. Para etapas, limites e permissões, consulte Excluir usuários.

Para exclusão programática em lotes menores, use o endpoint /users/delete em vez de uma campanha de webhook.