Creating a webhook
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’ accounts with a promotion after they’ve performed a custom event a certain number of times.
If you want to learn more about what webhooks are and how you can use them in Braze, check out About webhooks before proceeding.
Step 1: Choose where to build your message
Not sure whether your message should be sent using a campaign or a Canvas? Campaigns are better for single, simple messaging campaigns, while Canvases are better for multi-step user journeys.
Steps:
- Go to Messaging > Campaigns and click Create Campaign.
If you are using the older navigation, you can find Campaigns under Engagement.
- Select Webhook, or, for campaigns targeting multiple channels, select Multichannel Campaign.
- Name your campaign something clear and meaningful.
- Add Teams and Tags as needed.
- Tags make your campaigns easier to find and build reports out of. For example, when using the Report Builder, you can filter by particular tags.
- Add and name as many variants as you need for your campaign. You can choose different webhook templates for each of your added variants. For more on this topic, refer to Multivariate and A/B testing.
If all of the messages in your campaign are going to be similar or have the same content, compose your message before adding additional variants. You can then choose Copy from Variant from the Add Variant dropdown.
Steps:
- Create your Canvas using the Canvas composer.
- After you’ve set up your Canvas, add a step in the Canvas builder. Name your step something clear and meaningful.
- Choose a step schedule and specify a delay as needed.
- Filter your audience for this step as necessary. You can further refine the recipients of this step by specifying segments and adding additional filters. Audience options will be checked after the delay at the time messages are sent.
- Choose your advancement behavior.
- Choose any other messaging channels which you would like to pair with your message.
Step 2: Compose your webhook
You can choose to build a webhook from scratch or use one of our existing templates. Then, build your webhook in the Compose tab of the editor.
The Compose tab consists of the following fields:
Language
Internationalization is supported in the URL and the request body. To internationalize your message, click Add Languages and fill out the required fields. We recommend selecting your languages before writing your content so you can fill in your text where it belongs in the Liquid. See our full list of available languages.
Webhook URL
The webhook URL, or 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).
You can personalize your webhook URLs using Liquid. At times, certain endpoints may require you to identify a user or provide user-specific information as part of your URL. When using Liquid, make sure to include a default value for each piece of user-specific information that you use in your URL.
Request body
The request body is the information that will be sent to the URL that you specified. There are two ways to create the body of your webhook request:
JSON key-value pairs
JSON key-value pairs allow you to easily write a request for an endpoint that expects a JSON format. 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!
. After 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.
You can personalize your key-value pairs using Liquid, such as including 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!
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. Both personalization and internationalization using Liquid is supported in raw text.
If you set the Content-Type
request header to application/x-www-form-url-encoded
, the request body must be formatted as a URL-encoded string. For example:
1
to={{custom_attribute.${example}}}&text=Your+order+just+arrived
Step 3: Configure additional settings
Request headers (optional)
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 request headers are Content-Type
specifications (which describe what type of data to expect in the body, such as XML or JSON) and authorization headers that contain your credentials with your vendor or system.
Content type specifications must use the key Content-Type
. Common values are application/json
or application/x-www-form-urlencoded
.
Authorization headers must use the key Authorization
. Common values are Bearer {{YOUR_TOKEN}}
or Basic {{YOUR_TOKEN}}
where YOUR_TOKEN
is the credentials provided by your vendor or system.
HTTP method
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.
Step 4: Test send your message
Before making your campaign go live, Braze recommends that you test the webhook to make sure the request is formatted properly.
To do so, switch to the Test tab and send a test webhook. You can test the webhook as a random user, a specific user (by entering their email address of external user ID), or a customized user with attributes of your choosing.
After sending the test webhook, a dialog will appear with the response message. If the webhook request is unsuccessful, refer to the error message for assistance in troubleshooting your webhook. The following example details the response of a webhook with an invalid webhook URL.
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
}
}
Step 5: Build the remainder of your campaign or Canvas
Next, build the remainder of your campaign. See the following sections for further details on how to best use our tools to build webhooks.
Choose delivery schedule or trigger
Webhooks can be delivered based on a scheduled time, an action, or based on an API trigger. For more, refer to Scheduling your campaign.
For action-based delivery, you can also set the campaign’s duration and Quiet Hours.
This step is also where you can specify delivery controls, such as allowing users to become re-eligible to receive the campaign, or enabling frequency capping rules.
Choose users to target
Next, you need to target users by choosing segments or filters to narrow down your audience. In this step, you will select the larger audience from your segments, and narrow that segment further with our filters, if you choose. You’ll automatically be given a snapshot of what that approximate segment population looks like right now. Keep in mind that exact segment membership is always calculated just before the message is sent.
Choose conversion events
Braze allows you to track how often users perform specific actions, conversion events, after receiving a campaign. You have the option of allowing up to a 30-day window during which a conversion will be counted if the user takes the specified action.
If you haven’t done so already, complete the remaining sections of your Canvas step. For further details on how build out the rest of your Canvas, implement multivariate testing and Intelligent Selection, and more, refer to the Build your Canvas step of our Canvas documentation.
Step 6: Review and deploy
After you’ve finished building the last of your campaign or Canvas, review its details, test it, then send it!
Things to know
Errors, retry logic, and timeouts
Webhooks rely on Braze 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 to make 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 Message Activity Log.
This description contains the time the error occurred, the app name, and the error message:
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 the 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 following 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 |
For 500-level errors, Braze will retry the webhook send up to 5 times over 30 minutes using exponential backoff. For all other errors, Braze will continue to retry for up to 24 hours.
Each webhook is allowed 90 seconds before it times out.
IP allowlisting
When a webhook is sent from Braze, the Braze servers make network requests to our customers or third-party servers. With IP allowlisting, you can verify that webhook requests are coming from Braze, adding a layer of security.
Braze will send webhooks from the following IPs. The listed IPs are automatically and dynamically added to any API keys that have been opted-in for allowlisting.
If you’re making a Braze-to-Braze webhook and using allowlisting, you should allowlist all the following IPs, including 127.0.0.1
.
For Instances US-01 , US-02 , US-03 , US-04 , US-05 , US-06 , and US-07 : |
---|
127.0.0.1 |
23.21.118.191 |
34.206.23.173 |
50.16.249.9 |
52.4.160.214 |
54.87.8.34 |
54.156.35.251 |
52.54.89.238 |
18.205.178.15 |
For Instances EU-01 and EU-02 : |
---|
127.0.0.1 |
52.58.142.242 |
52.29.193.121 |
35.158.29.228 |
18.157.135.97 |
3.123.166.46 |
3.64.27.36 |
3.65.88.25 |
3.68.144.188 |
3.70.107.88 |
For Instance US-08 : |
---|
52.151.246.51 |
52.170.163.182 |
40.76.166.157 |
40.76.166.170 |
40.76.166.167 |
40.76.166.161 |
40.76.166.156 |
40.76.166.166 |
40.76.166.160 |
40.88.51.74 |
52.154.67.17 |
40.76.166.80 |
40.76.166.84 |
40.76.166.85 |
40.76.166.81 |
40.76.166.71 |
40.76.166.144 |
40.76.166.145 |
Using webhooks with Braze partners
There are many ways to use webhooks, and with our technology partners (Alloys), you can use webhooks to level up your communication directly with your customers and users.
Check out:
- Messenger
- Remerge
- Lob.com
- And many more of our technology partners!