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? As Campaigns são melhores para campanhas de mensagens únicas e direcionadas. Já os Canvas são mais indicados para jornadas do usuário com várias etapas.

• campaign
• canvas

Etapas:

1. Acesse Mensagens > Campaigns e selecione Criar campanha.
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 explicar como essa campanha será usada.
5. Adicione equipes e tags conforme necessário.
   • As tags facilitam encontrar suas campanhas e criar relatórios com base nelas. Por exemplo, ao usar o Criador de relatórios, você pode filtrar por tags específicas.
6. Adicione e nomeie quantas variantes precisar para sua campanha. Você pode escolher modelos de webhook diferentes para cada uma das variantes adicionadas. Para saber mais sobre esse tópico, consulte Testes multivariantes e Testes A/B.

Dica

Se todas as mensagens da sua campanha forem parecidas ou tiverem o mesmo conteúdo, crie sua mensagem antes de adicionar outras variantes. Depois, 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 criar um novo webhook, usar um modelo existente ou usar um dos nossos modelos já disponíveis. Em seguida, crie seu webhook na guia Compor do editor.

A guia Compor tem os seguintes campos:

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

Idiomas

Você pode enviar um único webhook para usuários em vários mercados usando mensagens multilíngues. A tradução é compatível com o corpo da solicitação e com a URL do webhook.

Para localizar um webhook:

1. Crie as localidades que você deseja oferecer no seu espaço de trabalho.
2. Na guia Compor, envolva com tags de tradução apenas o texto que você quer traduzir. Por exemplo, {% translation greeting %}Hello!{% endtranslation %}.
3. Selecione Gerenciar idiomas, escolha suas localidades e adicione as 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 conferir a prévia de cada localidade antes do envio.

Importante

Envolva com tags de tradução apenas valores legíveis por pessoas. Nunca envolva chaves JSON, colchetes, vírgulas ou outros elementos de estrutura. Os tradutores podem alterar ou remover caracteres especiais, o que pode gerar um corpo de solicitação malformado que seu endpoint rejeitará.

Em um corpo de solicitação criado com pares de chave-valor JSON, coloque 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 for diferente em cada mercado, você pode envolver parte da URL com tags de tradução. Mantenha o protocolo (https://) fora das tags e não inclua parâmetros de consulta dentro delas. Para saber mais, consulte Localizar URLs.

Modelos de webhook

Os modelos de webhook aceitam traduções salvas. Assim, você pode localizar um modelo uma única vez e reutilizá-lo em Campaigns e etapas do Canvas. Você precisa da permissão Edit Webhook Templates para adicionar localidades 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ê vai enviar as informações capturadas no webhook.

Se quiser enviar informações para um fornecedor, ele deve informar essa URL na documentação da API dele. Se estiver enviando informações para seus próprios sistemas, confirme com sua equipe de desenvolvimento ou engenharia se você está usando a URL correta.

A Braze só permite 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. Às vezes, alguns endpoints exigem que você identifique um usuário ou forneça informações específicas do usuário na URL. Ao usar Liquid, inclua 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 de acordo com o endpoint para o qual você está enviando as informações. Na maioria dos casos, você vai 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 seu webhook com pares de chave-valor JSON ou texto bruto.

Pares de chave-valor JSON

Os pares de chave-valor JSON facilitam a criação de uma solicitação para um endpoint que espera o formato JSON. Você só pode usar essa opção com um endpoint que espera uma solicitação JSON. Por exemplo, se a sua chave for message_body, o valor correspondente poderia ser Your order just arrived!. Depois que você inserir o par de chave-valor, o criador vai configurar sua solicitação na sintaxe JSON, e uma prévia da solicitação JSON será preenchida automaticamente.

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

Texto bruto

A opção de texto bruto oferece flexibilidade para criar uma solicitação para um endpoint que espera um corpo em qualquer formato. Por exemplo, você pode usá-la para criar uma solicitação para um endpoint que espera receber os dados em formato XML.

Tanto a personalização quanto as tags de tradução 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 deverá estar formatado como uma string codificada para URL. Por exemplo:

1

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

Etapa 3: Defina configurações adicionais

Usar uma credencial salva (opcional)

Use uma credencial salva para autenticar um webhook sem inserir a senha ou o token na mensagem. Você pode reutilizar credenciais de autenticação básica e de autenticação por token de Configurações > Gerenciamento de credenciais em campanhas de webhook, etapas do Canvas e modelos de webhook.

As credenciais pertencem a um único espaço de trabalho. Crie a credencial em cada espaço de trabalho onde você precisar dela, incluindo espaços de trabalho separados de desenvolvimento, homologação e produção.

Para selecionar uma credencial existente, você precisa da permissão “Manage App Group” ou da permissão de edição correspondente: “Edit Campaigns”, “Edit Canvases” ou “Edit Webhook Templates”. Para criar, editar ou excluir credenciais, você precisa da permissão “Manage App Group”. Se necessário, peça ao administrador do seu espaço de trabalho para concedê-la.

1. Na guia Compor, insira um URL de webhook HTTPS com um nome de host fixo, como https://api.example.com/events. Você pode usar Liquid no caminho ou nos parâmetros de consulta, mas o nome de host precisa ser estático para selecionar uma credencial.
2. Em Credencial, selecione uma credencial salva. A lista mostra as credenciais cujo domínio permitido corresponde ao nome de host do URL, incluindo credenciais que permitem um domínio pai.
3. Se você tiver permissão para criar credenciais, selecione Adicionar credencial no seletor para criar uma. Selecione Autenticação básica ou Autenticação por token, insira um nome exclusivo para a credencial e os detalhes de autenticação e selecione Adicionar credencial. O domínio permitido é preenchido com base no nome de host do webhook e não pode ser alterado nesse formulário.
4. Confirme a credencial selecionada antes de salvar ou enviar um webhook de teste.

Se o nome de host vier do Liquid ou de um Content Block, mantenha a autenticação em Cabeçalhos da solicitação. Para usar uma credencial salva, altere o URL para um nome de host fixo e mantenha os valores dinâmicos no caminho ou nos parâmetros de consulta.

Os dois tipos de credencial exigem um domínio permitido para uso em webhooks. Uma credencial de autenticação básica sem domínio ainda pode ser usada no Connected Content, mas não fica disponível no seletor de webhook. Confira a coluna Disponível em na página Gerenciamento de credenciais para confirmar se uma credencial é compatível com webhooks. Para ver exemplos de configuração e de domínio, consulte Tipos de autenticação.

Aviso

O domínio permitido de uma credencial inclui todos os seus subdomínios. Use o nome de host mais específico que sua organização controla. Um domínio pai compartilhado pode permitir que o subdomínio de outra organização receba sua credencial. Consulte Escolher um domínio permitido.

A Braze aplica a autenticação salva ao enviar a solicitação. A autenticação básica fornece o cabeçalho Authorization. A autenticação por token fornece os cabeçalhos salvos na credencial. Se você inserir manualmente um cabeçalho com o mesmo nome, o valor da credencial salva terá prioridade. Os nomes de cabeçalho não diferenciam maiúsculas de minúsculas.

Se você alterar o URL e a credencial selecionada deixar de corresponder a ele, o criador limpa a seleção. Selecione novamente uma credencial correspondente antes de salvar. A Braze também valida a credencial e o URL de destino renderizado no momento do envio. Uma credencial inválida ou um destino não permitido impede o envio do webhook.

Para atualizar ou remover uma credencial salva, consulte Gerenciar credenciais salvas.

Prévia de credenciais salvas

A prévia do webhook mostra o URL renderizado, o corpo e os cabeçalhos da solicitação inseridos manualmente. Ela omite a referência à credencial selecionada e os cabeçalhos de autenticação fornecidos por essa credencial, em vez de mostrar valores mascarados. A Braze aplica a credencial salva ao enviar um webhook de teste ou ativo.

No criador, usuários sem a permissão “Manage App Group” ou a permissão de edição correspondente veem Oculto no seletor Credencial desativado quando há uma credencial selecionada. Eles não podem visualizar nem alterar a seleção.

Cabeçalhos da solicitação (opcional)

Alguns endpoints podem exigir que você inclua cabeçalhos na solicitação. Na seção Compor 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 dado esperado no corpo, como XML ou JSON) e os cabeçalhos Authorization, que contêm suas credenciais com seu fornecedor ou sistema.

Nota

Os nomes de cabeçalho HTTP não diferenciam maiúsculas de minúsculas, de acordo com a RFC 7230, seção 3.2 (“Each header field consists of a case-insensitive field name”). Se o endpoint de recebimento ou qualquer serviço intermediário (como CDNs) alterar a capitalização dos cabeçalhos, isso não afetará o processamento: Content-Type, content-type e CONTENT-TYPE são todos tratados da mesma forma.

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: Teste o envio da sua mensagem

Antes de colocar sua campanha em funcionamento, a Braze recomenda testar o webhook para garantir que a solicitação esteja formatada corretamente. Se você selecionou uma credencial salva, o envio de teste a utilizará para autenticar a solicitação.

Para isso, acesse 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 dele) ou um usuário personalizado com os atributos que preferir.

Depois de 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 mostra a resposta de um webhook com um URL de webhook inválido.

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 de sua Campaign ou Canvas

• campaign
• canvas

Agora, crie o restante de sua Campaign. Confira as seções a seguir para saber como aproveitar melhor nossas ferramentas na criação de webhooks.

Escolha o cronograma ou o gatilho de entrega

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

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

Nesta etapa, você também pode especificar controles de entrega. Por exemplo, é possível permitir que os usuários se tornem novamente elegíveis para receber a Campaign ou ativar regras de limite de frequência.

Escolha os usuários-alvo

Em seguida, você deve direcionar os usuários escolhendo Segments ou filtros para restringir seu público. Nesta etapa, você seleciona o público maior a partir de seus Segments e, se quiser, restringe ainda mais esse Segment com nossos filtros. Você recebe automaticamente uma prévia de como está a população aproximada desse Segment. Lembre-se de que a associação exata ao Segment é 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 rastrear com que frequência os usuários realizam ações específicas, os eventos de conversão, depois de receberem uma Campaign. Você pode 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 fez isso, conclua as seções restantes da etapa do Canvas. Para saber mais sobre como criar o restante do seu Canvas, incluindo testes multivariantes e Otimizar com BrazeAI^TM, consulte Crie seu Canvas.

Etapa 6: Revise e implemente

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

Informações importantes

Erros, lógica de nova tentativa e tempos limite

Os webhooks dependem de solicitações que os servidores da Braze fazem a um endpoint externo, então erros podem acontecer de vez em quando. Os erros mais comuns incluem erros de sintaxe, chaves de API expiradas, limites de frequência e problemas inesperados no servidor. Antes de enviar uma Campaign de webhook:

• Teste seu webhook para verificar se há erros de sintaxe
• Confira se as variáveis personalizadas têm valores padrão

Se o envio do webhook falhar, uma mensagem de erro é registrada no Registro de atividades de mensagens. Ela inclui detalhes como o registro de data e hora do erro, o nome do app e informações sobre o erro.

Se a mensagem de erro não deixar clara a origem do problema, confira a documentação do endpoint da API que você está usando. Normalmente, ela explica os códigos de erro do endpoint e o que costuma causá-los.

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

Quando a solicitação do webhook é enviada, o servidor de destino retorna um código de resposta indicando o que aconteceu com ela. A tabela a seguir resume as diferentes respostas que o servidor pode enviar, como elas afetam a análise de dados da Campaign e se, em caso de erro, a Braze tentará entregar a Campaign novamente:

Nota

A Braze faz novas tentativas para os códigos de status desta seção que permitem repetição, com até cinco tentativas no total (a solicitação inicial mais quatro novas tentativas) e um intervalo crescente entre elas. Se a Braze não conseguir acessar seu endpoint, as novas tentativas podem continuar por até 24 horas.

Cada solicitação de webhook tem 120 segundos antes de atingir o tempo limite.

Os cabeçalhos de resposta Retry-After e de limite de frequência podem afetar quanto tempo a Braze espera antes de uma tentativa repetível (por exemplo, depois de 408, 429 ou 5XX). Eles não tornam elegíveis para nova tentativa as respostas não repetíveis, como 401.

Nota

Se os envios de webhook parecerem ausentes da análise de dados, abra o Registro de atividades de mensagens da Campaign ou da etapa do Canvas. A Braze só faz novas tentativas para certas respostas (por exemplo, 408, 429 e 5XX). A maioria dos outros erros de cliente 4XX, incluindo 401 Unauthorized, não gera novas tentativas. Para ver 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}

Uma resposta 403 Forbidden significa 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 um firewall ou um firewall de aplicativos web) que bloqueiam os endereços IP de saída da Braze.

Se as solicitações de webhook retornarem 403 com frequência e seus cabeçalhos de autenticação estiverem corretos, adicione os IPs da Braze do seu cluster à lista de permissões do servidor que recebe o webhook. Consulte Lista de permissões de IP. As solicitações de conteúdo conectado usam os mesmos IPs de saída. Consulte Lista de permissões de IP do conteúdo conectado.

Para outras etapas de solução de problemas de 4XX, consulte Solução de problemas de solicitações de webhook e conteúdo conectado.

Autenticação e credenciais do conteúdo conectado

Selecione uma credencial no criador de webhook para autenticar a solicitação de saída. Nesta página, consulte Usar uma credencial salva.

As opções de Liquid :basic_auth e :auth_credentials autenticam apenas a chamada {% connected_content %} em que aparecem. Elas não selecionam uma credencial para a solicitação principal do 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 de corpo, para que o Liquid a resolva antes de o webhook ser enviado.

Modelos de webhook salvos e uso em Campaigns

A Braze não oferece 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 usam 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 ver explicações detalhadas, etapas de solução de problemas e orientações sobre como resolver erros específicos de webhook, consulte Solução de problemas de solicitações de webhook e conteúdo conectado. Lá você também encontra mais explicações sobre como funciona nosso sistema de detecção de hosts com problemas e como a Braze envia notificações de erro por e-mails automáticos e registros adicionais 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 extra de segurança.

A Braze enviará webhooks a partir dos IPs a seguir. Os IPs listados são adicionados de forma automática e dinâmica a todas as chaves de API que foram habilitadas para a lista de permissões.

Importante

Se você estiver criando um webhook da Braze para a Braze e usando a lista de permissões, adicione todos os IPs a seguir à lista, 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 permite a exclusão em massa por Segment (até 10 milhões de perfis), inclui um período de cancelamento de 7 dias e não consome os limites de frequência compartilhados da REST API. Para conhecer as etapas, os limites e as permissões, consulte Excluir usuários.

Para exclusões programáticas em lotes menores, use o endpoint /users/delete em vez de uma Campaign de webhook.