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 tem certeza 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 é melhor 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 e a criação de relatórios das suas campanhas. 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: Crie seu webhook

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

A guia Compose é composta pelos seguintes campos:

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

Idioma

A internacionalização é compatível com a URL e o corpo da solicitação. Para internacionalizar sua mensagem, selecione Add languages e preencha os campos obrigatórios.

Recomendamos selecionar seus idiomas antes de escrever o conteúdo para que você possa preencher o texto no local correto no Liquid. Para ver a lista completa de idiomas disponíveis, consulte Idiomas compatíveis.

Se você estiver adicionando texto em um idioma escrito da direita para a esquerda, a aparência final das mensagens da direita para a esquerda depende em grande parte de como os provedores de serviço as renderizam. Para conhecer as práticas recomendadas sobre como criar mensagens da direita para a esquerda que sejam exibidas com a maior precisão possível, consulte Criação de mensagens da direita para a esquerda.

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, ele 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 do seu webhook usando Liquid. Em alguns casos, determinados 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, inclua um valor padrão para cada informação específica do usuário que você utilizar na URL.

Método HTTP

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

Corpo da solicitação

O corpo da solicitação são as informações que serão enviadas para a URL que você especificou. Você pode criar o corpo da solicitação do seu 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á preenchida automaticamente.

Você pode personalizar seus pares de chave-valor usando Liquid, incluindo 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 a internacionalização usando Liquid são compatíveis com 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)

Alguns 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 da solicitação, como XML ou JSON) e os cabeçalhos de Authorization, que contêm suas credenciais com o fornecedor ou sistema.

Nota

Os nomes dos 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: Envie uma mensagem de teste

Antes de ativar sua campanha, a Braze recomenda que você teste o webhook para garantir que a solicitação esteja formatada corretamente.

Para isso, alterne 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 de sua escolha.

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: Crie o restante da sua campanha ou Canvas

• campaign
• canvas

Em seguida, crie 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 a serem direcionados

Em seguida, você deve direcionar os usuários escolhendo segmentos ou filtros para refinar seu público. Nesta etapa, você seleciona o público mais amplo a partir dos seus segmentos e, se desejar, refina ainda mais esse segmento com nossos filtros. Você recebe automaticamente uma prévia de como é a população aproximada desse segmento. Lembre-se de que a composição exata 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ê acompanhe a frequência com que os usuários realizam ações específicas, chamadas eventos de conversão, após receberem uma campanha. Você tem a opção de definir uma janela de até 30 dias durante a qual uma conversão será contabilizada se o usuário realizar a ação especificada.

Se ainda não tiver feito isso, conclua as seções restantes da sua etapa do Canvas. Para mais detalhes sobre como criar o restante do seu Canvas, implementar testes multivariantes e seleção inteligente, e muito mais, consulte a etapa Crie seu Canvas na nossa documentação do 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 nova tentativa e tempos limite

Os webhooks dependem dos servidores da Braze para fazer solicitações 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 para verificar 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 e incluirá detalhes como o timestamp do erro, o nome do app e informações sobre o erro.

Se a mensagem de erro não for clara o suficiente sobre a origem do problema, consulte a documentação do endpoint de API que você está usando. Normalmente, ela fornece uma explicação dos códigos de erro que o endpoint utiliza e suas causas mais comuns.

Códigos de resposta e lógica de nova tentativa

Quando a solicitação de 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 a análise de dados da campanha e se, em caso de erros, a Braze tentará reenviar a campanha:

Nota

A Braze faz novas tentativas para os códigos de status mencionados anteriormente nesta seção até cinco vezes em 30 minutos, usando backoff exponencial. Se não for possível alcançar seu endpoint, as novas tentativas podem se estender por um período de 24 horas.

Cada webhook tem um tempo limite de 90 segundos.

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 com possibilidade de nova tentativa (por exemplo, após 408, 429 ou 5XX). Eles não tornam respostas sem possibilidade de nova tentativa, como 401, elegíveis para nova tentativa.

Nota

Se os envios de webhook parecerem estar ausentes na análise de dados, abra o Registro de atividade de mensagens da campanha ou etapa do Canvas. A Braze faz novas tentativas apenas para 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 nova tentativa.

403 Forbidden e lista de permissões de IP {#403-forbidden-and-ip-allowlisting}

Respostas 403 Forbidden significam que seu endpoint recebeu a solicitação, mas a recusou. As causas mais comuns incluem autenticação inválida ou ausente, permissões de API insuficientes e regras de rede (como 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 permissões de IP. As solicitações de Connected Content usam os mesmos IPs de saída; consulte Lista de permissões de IP do Connected Content.

Para outras etapas de solução de problemas com 4XX, consulte Solucionar problemas de solicitações de webhook e Connected Content.

Autenticação e credenciais de Connected Content

A solicitação HTTP de webhook de saída não suporta a anexação de credenciais de Connected Content (:basic_auth ou :auth_credentials) para autenticação no seu endpoint. Em vez disso, configure a autenticação usando Cabeçalhos da solicitação no webhook. Para buscar um token ou segredo no momento do envio, você pode inserir 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 a mesma 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, etapas de solução de problemas e orientações sobre como resolver erros específicos de webhook, consulte Solucionar problemas de solicitações de webhook e Connected Content. Você também encontrará mais explicações sobre como nosso sistema de detecção de hosts não íntegros funciona e como a Braze fornece notificações de erro por meio de e-mails automatizados e registro adicional no Braze Currents.

Lista de permissões de IP

Quando um webhook é enviado pela Braze, os servidores da Braze fazem solicitações de rede para os servidores de nossos clientes ou de terceiros. Com a lista de permissões de IP, 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 quaisquer chaves de API que tenham sido habilitadas para a lista de permissões.

Importante

Se você estiver fazendo um webhook de Braze para Braze e usando a lista de permissões, adicione 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 segmento de usuários, acesse Público > Gerenciar público > Excluir usuários. O dashboard suporta exclusão em massa de segmentos (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.