Criando uma campanha de webhook

Criar uma campanha de webhook ou incluir um webhook em uma campanha multicanal permite que você acione ações fora do aplicativo, fornecendo a outros sistemas e aplicativos informações em tempo real.

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

Passo 1: Escolha onde construir sua mensagem

Não tem certeza se sua mensagem deve ser enviada usando uma campanha ou um Canvas? Campanhas são melhores para campanhas de mensagens únicas e simples, enquanto Canvases são melhores para jornadas de usuários em várias etapas.

• campaign
• canvas

Etapa 2: Construa seu webhook

Você pode escolher criar um webhook do zero, usar um modelo existente ou usar um de nossos modelos existentes. Em seguida, construa seu webhook na aba Compor do editor.

A aba Compor consiste nos seguintes campos:

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

!A aba “Compor” com um exemplo de modelo de webhook.

Idioma

Internacionalização é suportada na URL e no corpo da solicitação. Para internacionalizar sua mensagem, selecione Adicionar idiomas e preencha os campos obrigatórios.

Recomendamos selecionar seus idiomas antes de escrever seu conteúdo para que você possa preencher seu texto onde ele pertence no Liquid. Para nossa lista completa de idiomas disponíveis que você pode usar, consulte Idiomas suportados.

Se você estiver adicionando texto em um idioma que é escrito da direita para a esquerda, observe que a aparência final das mensagens da direita para a esquerda depende em grande parte de como os provedores de serviços as renderizam. Para melhores práticas na elaboração de mensagens da direita para a esquerda que sejam exibidas da forma mais precisa possível, consulte Criando mensagens da direita para a esquerda.

URL do Webhook

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

Se você deseja enviar informações para um fornecedor, o fornecedor deve fornecer esta URL em sua documentação de API. Se você estiver enviando informações para seus próprios sistemas, verifique com sua equipe de desenvolvimento ou engenharia para confirmar se está usando a URL correta.

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

Usando Liquid

Você pode personalizar suas URLs de webhook 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 sua URL. Ao usar Liquid, certifique-se de incluir um valor padrão para cada informação específica do usuário que você usar em sua 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 sua solicitação de webhook com pares chave-valor JSON ou texto bruto.

Pares chave-valor JSON

Pares 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 chave-valor, o compositor configurará sua solicitação na sintaxe JSON, e uma prévia da sua solicitação JSON será preenchida automaticamente.

!Corpo da solicitação definido para pares chave-valor JSON.

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

Texto bruto

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

Tanto a personalização quanto a internacionalização usando Liquid são suportadas em texto bruto.

!Um exemplo de um corpo de solicitação com texto bruto usando Liquid.

Se você definir o Content-Type cabeçalho de solicitação para 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

!Corpo da solicitação com string codificada em URL.

Passo 3: Configurar configurações adicionais

Cabeçalhos de solicitação (opcional)

Certos endpoints podem exigir que você inclua cabeçalhos em sua solicitação. Na seção Compor do compositor, você pode adicionar quantos cabeçalhos forem necessários.

!Exemplos de cabeçalhos de solicitação para a chave “Authorization” e a chave “Content-type”.

Os cabeçalhos de solicitação comuns são Content-Type especificações (que descrevem que tipo de dados esperar no corpo, como XML ou JSON) e cabeçalhos de autorização que contêm suas credenciais com seu fornecedor ou sistema.

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

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

Passo 4: Teste o envio da sua mensagem

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

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

Após enviar o webhook de teste, um 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 assistência na solução de problemas do seu webhook. O seguinte exemplo 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
  }
}

Passo 5: Construa o restante da sua campanha ou Canvas

• campaign
• canvas

Passo 6: Revisar e implantar

Depois de terminar de construir a última parte da sua campanha ou Canvas, revise seus detalhes, teste-o e, em seguida, envie-o!

Coisas a saber

Erros, lógica de repetição e timeouts

Webhooks dependem de servidores Braze fazendo 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 taxa e problemas inesperados do lado do servidor. Antes de enviar uma campanha de webhook:

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

Se o seu webhook falhar ao enviar, uma mensagem de erro será registrada no Registro de Atividade de Mensagem, e incluirá detalhes como o timestamp do erro, nome do aplicativo e detalhes sobre o erro.

!Erro de webhook com a mensagem “Um token de acesso ativo deve ser usado para consultar informações sobre o usuário atual”.

Se a mensagem de erro não for clara o suficiente em relação à origem do erro, você deve verificar a documentação do endpoint da API que está usando. Esses geralmente fornecem uma explicação dos códigos de erro que o endpoint usa, bem como o que normalmente os causa.

Códigos de resposta e lógica de repetição

Quando a solicitação de webhook é enviada, o servidor receptor retornará 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 da campanha e se, no caso de erros, a Braze tentará reenviar a campanha:

Solução de problemas e detalhes adicionais de erro

Para explicações detalhadas, etapas de solução de problemas e orientações sobre como resolver erros específicos de webhook, consulte Troubleshooting webhook and Connected Content requests. Você também encontrará mais explicações sobre como nosso sistema de detecção de hosts não saudáveis 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 da Braze, os servidores da Braze fazem solicitações de rede para nossos clientes ou servidores de terceiros. Com a lista de permissão 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 dos seguintes IPs. Os IPs listados são adicionados automaticamente e dinamicamente a qualquer chave de API que tenha sido optada para a lista de permissão.

• united states (us)
• european union (eu)
• australia (au)
• indonesia (id)

Usando webhooks com parceiros da Braze

Existem muitas maneiras de usar webhooks, e com nossos parceiros de tecnologia (Alloys), você pode usar webhooks para aprimorar sua comunicação diretamente com seus clientes e usuários.

Confira:

• Messenger
• Remerge
• Lob.com
• E muitos mais de nossos parceiros de tecnologia!