Something BIG is happening to our documentation! Check back in early October!

Creating a Webhook

Feature Overview

Creating a webhook campaign or including a webhook in a multichannel campaign allows you to trigger non-app actions. More specifically, webhooks can be used to provide other systems and applications with real-time information. You can use webhooks to send information to systems such as Salesforce or Marketo. You can also use webhooks to send information to your backend systems. For example, you might want to credit your customers account with a promotion once they’ve performed a custom event a certain number of times.

Creating a Webhook

Step 1: Set Up a Webhook

Add a new webhook message to a Campaign or Canvas. You can then choose to build a webhook from scratch or use one of our existing templates.

Step 2: Enter the URL for Your Webhook

HTTP URL

Enter the HTTP URL. This HTTP URL specifies your endpoint. The endpoint is the place where you’ll be sending the information that you’re capturing in the webhook. If you’d like to send information to a vendor, the vendor should provide this URL in their API documentation. If you’re sending information to your own systems, check with your development or engineering team to ensure that you’re using the correct URL. Braze only allows URLs that communicate over standard ports 80 (HTTP) and 443 (HTTPS).

Personalization

Personalization is supported in our HTTP URLs. At times, certain endpoints may require you to identify a user or provide user-specific information as part of your URL. You’ll want to be sure to include a default value for each piece of user specific information that you use in your URL.

Internationalization

Internationalization is supported in the URL and the request body. To internationalize your message, click ‘add languages’ and fill out the flyout.

Step 3: Create the Request Body

Create the body of your webhook request. This is the information that will be sent to the URL that you specified. There are two ways to create the body of your web hook request:

JSON Key-Value Pairs

JSON key-value pairs allow you to easily write a request for an endpoint that expects a JSON format. Do note that you can only use this feature with an endpoint that expects a JSON request. For example, if your key is “message_body,” the corresponding value might be “Your order just arrived.” Once you’ve entered your key-value pair, the composer will configure your request in JSON syntax and a preview of your JSON request will automatically populate.

Webhook_JSON

Raw Text

The raw text option gives you the flexibility to write a request for an endpoint that expects a body of any format. For example, you might use this feature to write a request for an endpoint that expects your request to be in XML format.

webhook_rawtext

Personalization

Personalization is supported in both the JSON key-value pairs option and the raw text option. You can include any user attribute, custom attribute or event property in your request. For example, you can include a customer’s first name and email in your request. Don’t forget to include a default value for each attribute.

Internationalization

Internationalization is supported in raw text.

Step 4: Request Headers and HTTP Method

Certain endpoints may require that you include headers in your request. In the settings section of the composer, you can add as many headers as you’d like. Common use cases for request headers include a content type specification (e.g XML or JSON) and authorization headers that contain your credentials with your vendor or system. Content type specifications have the key “Content-Type” and common values are “application/json” or “application/x-www-form-urlencoded”.

The HTTP Method that you should use will vary depending on the endpoint to which you are sending information. The majority of the time, you’ll be using POST.

Webhook_Request_Header

Step 5: Test Send Your Message

Before making your campaign go live, you may wish to test send the webhook to make sure the request is formatted properly. To do so, navigate to the preview tab and send the test webhook. You can test the webhook for a random user, a specific user (by entering their email address of external user ID), or a customized user of with attributes of your choosing. If the request is successful a small message will appear at the top of your screen. If the webhook request is unsuccessful a modal will appear with the error response message. The screenshot below is an example of the response of a webhook with an invalid webhook URL.

Webhook Test Feature

Step 6: Continue Campaign Creation

Continuing creating your campaign the way that you normally would. As with all of our message types, you can preview what your request will look like for a particular user, random user or user with specific attributes in the preview section of the webhook composer.

Errors, retry logic and timeouts

Webhooks rely on Braze’s servers making requests to an external endpoint, and syntax and other errors may arise. The first step to avoiding webhook errors is to test your webhook campaign for syntax errors and making sure that personalized variables have a default value. However, webhooks may still fail due to issues like expired API keys, rate limits or unexpected server errors. If your webhook fails to send, an error message gets logged to the Developer Console, under “Message Activity Log.” This description contains the time the error occurred, the app name and the error message:

Webhook error

If the message body is not clear enough regarding the source of the error, you should check the documentation of the API endpoint you’re using. These typically provide an explanation of the error codes the endpoint uses as well as what they’re typically caused by.

Like other campaigns, Braze tracks the delivery of your webhook campaigns and conversions resulting from them. When the webhook request is sent, the receiving server will return a response code indicating what happened with the request. The below table summarizes the different responses the server may send, how they impact campaign analytics and whether, in the case of errors, Braze will try to redeliver the campaign:

Response code Marked as received? Retries?
20x (success) Yes N/A
30x (redirection) No No
408 (request timeout) No Yes
429 (rate limited) No Yes
Other 4xx (client error) No No
5xx (server error) No Yes

When retrying, Braze will make 5 attempts using exponential backoff for a period of approximately 30 minutes before aborting the individual webhook call.

Each webhook, or batch of webhooks, is allowed 120 seconds before it times out.

Twilio SMS & MMS

For this example, we’ll configure the Braze webhook channel to send SMS and MMS to your users, via Twilio’s message sending API. For your convenience, a Twilio webhook template is included on the dashboard.

HTTP URL

The Webhook URL is provided by Twilio in your dashboard. This URL is unique to your Twilio account, since it contains your Twilio account ID (TWILIO_ACCOUNT_SID).

In our Twilio example, the webhook URL is https://api.twilio.com/2010-04-01/Accounts/TWILIO_ACCOUNT_SID/Messages.json. You can find this URL in the Getting Started section of the Twilio console.

Twilio_Console

Request Body

The Twilio API expects the request body to be URL-encoded, so we have to start by changing the request type in the Braze webhook composer to Raw Text. The required parameters for the body of the request are To, From and Body.

The screenshot below is an example of what your request might look like if you are sending an SMS to each user’s phone number, with the body “Hello from Braze!”.

  • You’ll need to have valid phone numbers on each user profile in your target audience.
  • In order to meet Twilio’s request format, use the url_param_escape Liquid filter on your message contents. This filter encodes a string so all the characters are allowed in an HTML request; for example, the plus character (+) in the phone number +12125551212 is forbidden in URL-encoded data, and will be converted to %2B12125551212.

Webhook Body

Request Headers and Method

Twilio requires two request headers, the request Content-Type and an HTTP Basic Authentication header. Add them to your webhook by clicking the gear icon on the right side of the webhook composer, then clicking Add New Pair twice.

Header Name Header Value
Content-Type application/x-www-form-urlencoded
Authentication Basic {{ 'TWILIO_ACCOUNT_SID:TWILIO_AUTH_TOKEN' | base64_encode }}

Be sure to replace TWILIO_ACCOUNT_SID and TWILIO_AUTH_TOKEN with values from your Twilio dashboard. Lastly, Twilio’s API endpoint is expecting an HTTP POST request, so choose that option in the dropdown for HTTP Method.

Webhook Method

Preview Your Request

Use the webhook composer to preview the request for a random user, or for a user with particular credentials, to ensure that the request is rendering properly.

Webhook Preview

Lob Direct Mail Integration

Lob.com is an online service which one can interact with through their API to send direct mail like letters, postcards, and checks through the mail. You can access Lob’s services through Braze’s webhook feature and send mail to your users. To get started, sign up for an account on Lob.com and locate your API key in the settings section under your name in the dashboard.

Lob API Key

HTTP URL

The HTTP URL to request in the webhook is different for each action you can make to Lob. In this example we will be sending a postcard so the url is https://api.lob.com/v1/postcards, however the list of all the HTTP URL endpoints can be found in the Lob documentation.

Lob Endpoints

Request Body

To specify an address in the webhook body requires nested objects, and as such it must be entered as “Raw Text” in JSON format. If you are unfamiliar with the JSON format, an easy way to generate a sample request body is to copy the example CURL requests given on the Lob.com documentation and run it in your terminal (replacing their test API key with yours). Once you run the code in terminal, go to the Lob.com dashboard and check the “Logs” tab found under the “Requests” title. If the API request worked, you will be able to click on the request and copy the request body into the dashboard. You can then replace the data in the file to fit your desires.

Lob Success Response

Request Headers and Method

Lob’s documentation states that you must include your API key in the header to authorize the request. To do so, simply navigate to the setting section and add a new pair. For an authentication header, set the key to “Authorization”. Lob expects your API key to be base64 encoded, so use the Base64 filter in the header value: Basic APIkey:. You will need to add a “:” to the end of your API key when encoding as Lob expects the password to be left blank. Because the body of the request is in JSON format, you will also need to add a “Content-Type” key with the value “application/json”. The request method for this webhook is POST as specified on Lob’s documentation.

Lob Preview

Preview Your Request

At this point your campaign should be ready to send. If you run into errors, check the Lob dashboard and the developer console error message logs found in the Braze dashboard. Using these two resources you should be able to troubleshoot and debug your request. For example, the error below is caused by an incorrectly formatted authentication header.

Error Log Message

Facebook Messenger

Facebook Messenger is one of the world’s most popular instant messaging platforms, used by nearly one billion monthly active users. Brands are creating engaging Chatbots on the platform, and our Webhook interface helps you message your users on Facebook Messenger using the Messenger Platform APIs while taking full advantage of Braze’s advanced segmentation, personalization and triggering features. For your convenience, a Facebook Messenger webhook template is included on the dashboard.

In order to send messages, you’ll need a Facebook Messenger Page and App. We’ll assume you already have the requisites set up. If you need to do this, please see Facebook’s Messenger Platform Product Overview for help getting started. Braze also offers a full tutorial for creating a Messenger bot with example code in a GitHub repository!

Before starting, please note that Facebook does not allow usage of the Messenger Platform to send marketing messages. The platform is intended for “non-promotional messages that facilitate a pre-existing transaction, provide other customer support actions, or deliver content requested by a person.” To read more, see Facebook’s Platform Guidelines and Examples of Acceptable Use Cases. In addition, to send messages to users who are not test users of your Facebook App, your App will need to pass Facebook’s App Review.

Messenger IDs

In order to send messages on Facebook Messenger, you need to collect your users’ page-specific IDs (PSIDs). PSIDs are not the same as the user’s Facebook ID, and you’ll need the user’s explicit permission for messages from your page. To use PSIDs to send messages, embed a Send to Messenger or Message Us button in your web page or app and send the user’s PSID to Braze as a string custom attribute. You will also gain access to the user’s PSID in the back end if the user messages your page.

Facebook also supports the use of phone numbers to send messages on Messenger. Note that you’ll need to request the pages_messaging_phone_number permission separately in your App Review to use this feature. Additionally, all phone numbers need to be verified with Facebook by the user in order to receive messages on Messenger.

Setting up the Messenger Webhook

Every HTTP POST request to the Messenger Platform Send API needs to be accompanied by a page access token. If you don’t yet have one, please see Facebook’s documentation on obtaining one. Below is an example of the webhook settings, make sure to replace <ACCESS_TOKEN> with your access token. Also change the Request Body from key-value pairs to raw text to support multi-level JSON.

FBM webhook

You also need to set the Content-Type header to application/json in the webhook settings within Braze. To do this, click on the gear icon in the webhook configuration and add a key-value pair like this:

FBM Webhook headers

Formatting the Message

All requests to the Send API are sent in JSON according to a pre-specified format. The below examples are not exhaustive of all formats Facebook supports. Please see the Send API reference and its subsections for JSON definitions of all available message types and templates.

You can also use personalization and Connected Content in your webhook campaigns.

Text Messages

In order to send a text message to a user, use the following template, replacing the text with whatever message you wish to send:

{
  "recipient":{
    "id":"{{custom_attribute.${messenger_id}}}"
  },
  "message":{
    "text":"Hi {{${first_name} | default: 'there'}}! This is an example Facebook Messenger message."
  }
}

This message appears in Messenger as follows:

Example FBM text message

Media Messages

You can also use Facebook Messenger to send media such as images (including GIFs), videos, audio and files. You’ll need to host this media in a publicly accessible location where it can be accessed by URL, typically your web site. Just replace <YOUR_URL> in the template with the URL to your file and set type as image, audio, video or file depending on the content type you want to send:

{
  "recipient":{
    "id":"{{custom_attribute.${messenger_id}}}"
  },
  "message":{
    "attachment":{
      "type":"image",
      "payload":{
        "url":"<YOUR_URL>"
      }
    }
  }
}
Structured Messages and Templates

In addition to text and files, Facebook Messenger can be used to send structured messages containing buttons or content previews as well as templates like receipts. See the Send API reference for thorough descriptions of the JSON for all available templates as well as character limits and other limitations for copy.

The below webhook body will send a scrollable preview of a few articles in the Braze blog:

{
  "recipient":{
    "id":"{{custom_attribute.${messenger_id}}}"
  },
  "message":{
      "attachment":{
          "type":"template",
          "payload": {
              "template_type":"generic",
              "elements": [
                  {
                      "title": "The Rise and Rise of Emoji Marketing",
                      "image_url":"https://i2.wp.com/blog.appboy.com/wp-content/uploads/2016/07/emoji_blog_post.jpg?resize=720%2C346&ssl=1",
                      "subtitle":"Brands sent 800 million messages with emojis in June",
                      "buttons":[
                          {
                            "type":"web_url",
                            "url":"https://blog.appboy.com/emoji-marketing-world-emoji-day/",
                            "title":"Read More"
                          }
                      ]
                  },
                  {
                      "title": "What Emojis Really Mean to a Mobile Marketer",
                      "image_url":"https://i0.wp.com/blog.appboy.com/wp-content/uploads/2016/07/what-emojis-mean-to-a-marketer.jpg?resize=1250%2C600&ssl=1",
                      "subtitle":"An infoposter to remember World Emoji Day",
                      "buttons":[
                          {
                            "type":"web_url",
                            "url":"https://blog.appboy.com/emojis-really-mean-mobile-marketer/",
                            "title":"Read More"
                          }
                      ]
                  }
              ]
          }
      }
  }
}

This is the sample message in Messenger:

Example FBM structured message

Previewing and Testing Your Webhook

Before you send your message, test your webhook. Make sure your Messenger ID is saved in Braze (or find it and test as a Customized User), and use the preview to send the test message:

Sending a message to yourself

If you receive the message successfully, you can continue on to configure its delivery settings.

Targeting Facebook Messenger Users

If you are not sending messages using users’ phone numbers and plan on sending Messenger messages repeatedly, you should create a segment for all users for whom the Messenger ID exists as a custom attribute and turn on Analytics Tracking to track your Messenger subscription rates over time. If you choose not to create a specific segment for Messenger subscribers, make sure to include a filter for Messenger ID existing to avoid errors:

Segment filter for Messenger IDs

You may also use other segmentation to target your Messenger campaigns, and the rest of the campaign creation process is as with any other campaign.

Remerge Retargeting Network

For this example, we’ll configure the Braze webhook channel to connect Braze with retargeting actions. It is important to have an automatic way of enabling Braze and the retargeting system (i.e. Remerge) to have visibility of what the other system does and adapt from the other’s message. Ad retargeting is helpful if you have users who have push notifications disabled or users who haven’t opened your app recently.

For example: An unregistered user could receive a push campaign saying “Thanks for installing our app, sign up today!” Once the user has signed up after receiving the push campaign they would receive an adapted follow-up message in a retargeted ad such as “Thanks for signing up! Here is 10% off your first order.”

One of the best ways to accomplish this is to use Braze as well as a retargeting partner specialized in mobile, such as Remerge. You want the retargeting partner to receive automated user info from Braze using webhooks. You’ll be able to leverage Braze’s targeting and triggering abilities to send events to Remerge, which could then be used to define retargeting campaign definitions in remerge.io.

Request URL and Body

For this webhook, all data is passed on alongside the HTTP URL as query string parameters. There are three parameters that need to be defined:

  • You’ll need to set the event name. This is to define the name of the event that will appear in your remerge.io dashboard
  • Remerge requires you to pass along your app’s unique application identifier for Android (i.e. “com.example”) and iOS (i.e. “012345678”)
  • Finally you need to define a key. This will be provided by Remerge

Braze does not automatically collect the device IDFA/AAID so you must store these values yourself. Please be aware that you may require user consent to collect this data.

Below is an example of what your Webhook URL might look like:

{% assign event_name = "your_remerge_event_name" %}
{% assign android_app_id = "your_android_app_id" %}
{% assign iOS_app_id = "your_iOS_app_id" %}
{% assign remerge_key = "your_remerge_key" %}


{% capture json %}{"name":"{{event_name}}","active":true,"joined":{{"now" | date: "%s" }}}{% endcapture %}

https://remerge.events/event?partner=appboy&app_id={% if {{most_recently_used_device.${idfa}}} == blank %}{{android_app_id}}{% else %}{{iOS_app_id}}{% endif %}&key={{remerge_key}}&ts={{"now" | date: "%s" }}&{% if {{most_recently_used_device.${idfa}}} == blank %}aaid={{custom_attribute.${aaid}}}{% else %}idfa={{most_recently_used_device.${idfa}}}{% endif %}&event={{event_name}}&non_app_event=true&data={{json | url_param_escape}}

{% if {{most_recently_used_device.${idfa}}} == blank and {{custom_attribute.${aaid}}} == blank %}
{% abort_message('No IDFA or AAID available') %}
{% endif %}

After defining the parameters above, insert this liquid code template into the Webhook URL field and edit as needed. You do not have to define a Request Body for this webhook. Here is the template in Braze:

Webhook Template Remerge

Remerge used to offer multiple endpoints depending on where your data is stored, however, they have now updated their docs with one single endpoint:

https://remerge.events/event

The old endpoints are still valid and will stay valid, however, Remerge recommends that customers switch to this new endpoint for reliability purposes.

You can find more information on Remerge’s API endpoint here.

Request Headers and Method

This webhook does not require any Request Headers, but be sure to choose GET in the dropdown for the HTTP Method.

Request Method Remerge

Preview Your Request

To ensure the request is rendering properly for different users, use the Message Preview. A good approach is to preview the Webhook for both Android as well as iOS users. You can also send test requests for these users. If the request was successful the API responds with HTTP 204.

Creating a Webhook Template

Step 1: Navigate to the Webhook Template Editor

You can access the Webhook Template by first clicking the Campaigns tab under Engagement on the navigation bar, which will reveal a drop down menu with a ‘Templates and Styles’ tab. Click on this tab to access the Webhook Template Editor.

Webhook_template_campaign

Step 2: Create a New Template

You can now create a new template, edit an existing template or utilize one of the predesigned webhook templates that are offered. The pre-designed templates currently offered are for Twilio and Facebook messenger.

Step 3: Customize Your Template

Webhook templates can be used for many different use cases. You can start by entering a unique template name to be utilized. You can also fill in the webhook URL, the Request Body, Request Headers and select the HTTP Method to be used.

If you want to see how your webhook looks before sending it out to your users, you can send a test webhook through the Settings tab in the top right corner.

Webhook_template_test

Step 4: Save Your Template

Be sure to save your template by clicking the “Save Template” button in the bottom right corner of the editor. You’re now ready to use this template in any campaign you choose.

Webhook_template_save

Edits made to an existing template will not be reflected in campaigns that were created using the previous versions of that template.