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.

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 são melhores para jornadas de usuário com várias etapas.

• campaign
• canvas

Etapa 2: Crie seu webhook

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

A guia Compose consiste nos seguintes campos:

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

Idioma

A internacionalização é suportada na URL e no corpo da solicitação. Para internacionalizar sua mensagem, selecione Add languages 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 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 prestadores de serviço as renderizam. Para práticas recomendadas sobre como criar 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 para onde você enviará as informações que está capturando no webhook.

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

A Braze permite apenas URLs que se comunicam por 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 na 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 de chave-valor JSON ou texto bruto.

Pares de chave-valor JSON

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é-visualização 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 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 em formato XML.

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

Se você definir o cabeçalho de 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: Configure definições adicionais

Cabeçalhos de solicitação (opcional)

Certos 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.

Cabeçalhos de solicitação comuns são especificações de Content-Type (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 de tipo de conteúdo devem usar a chave Content-Type. Valores comuns são application/json ou application/x-www-form-urlencoded.

Os cabeçalhos de autorização devem usar a chave Authorization. Valores comuns são Bearer {{YOUR_TOKEN}} ou Basic {{YOUR_TOKEN}} onde 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 no ar, a Braze recomenda que você teste o webhook para garantir que a solicitação esteja formatada corretamente.

Para isso, mude para a guia Test 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 ID de usuário externo) ou um usuário personalizado com 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 ajudar 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 mais informações, consulte Enviar mensagens de teste.

Etapa 5: Construa o restante da sua campanha ou Canvas

• campaign
• canvas

Etapa 6: Revise e implante

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

O que você precisa saber

Erros, lógica de nova tentativa e timeouts

Webhooks dependem dos servidores da 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 no lado do servidor. Antes de enviar uma campanha de webhook:

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

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

Se a mensagem de erro não for clara o suficiente sobre a origem do erro, você deve verificar a documentação do endpoint de API que está usando. Normalmente, ela fornece uma explicação dos códigos de erro que o endpoint usa, bem como o que geralmente os causa.

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

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

Os cabeçalhos de resposta Retry-After e de limite de taxa podem afetar quanto tempo a Braze espera antes de uma tentativa que pode ser repetida (por exemplo, após 408, 429 ou 5XX). Eles não tornam respostas que não podem ser repetidas, como 401, elegíveis para nova tentativa.

Autenticação e credenciais de Conteúdo conectado

A solicitação HTTP de webhook de saída não suporta a anexação de credenciais de Conteúdo conectado (:basic_auth ou :auth_credentials) para autenticação no seu endpoint. Em vez disso, defina a autenticação usando Request headers 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 campanhas

A Braze não fornece um relatório integrado que liste todas as campanhas 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 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 Solução de problemas de solicitações de webhook e Conteúdo conectado. 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 pela Braze, os servidores da Braze fazem solicitações de rede para nossos clientes ou servidores de terceiros. Com a lista de permissões de IP, você pode verificar que 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 optado pela lista de permissões.

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