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.

• campaign
• canvas

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

• campaign
• canvas

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:

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.

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!