Skip to content

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.


  1. Go to Messaging > Campaigns and click Create Campaign.
  1. Select Webhook, or, for campaigns targeting multiple channels, select Multichannel Campaign.
  2. Name your campaign something clear and meaningful.
  3. 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.
  4. 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.


  1. Create your Canvas using the Canvas composer.
  2. After you’ve set up your Canvas, add a step in the Canvas builder. Name your step something clear and meaningful.
  3. Choose a step schedule and specify a delay as needed.
  4. 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.
  5. Choose your advancement behavior.
  6. 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.

Compose tab when creating a webhook in Braze

The Compose tab consists of the following fields:


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.

Request body set to JSON key-value pairs

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.

Request body set to 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:


Request body with URL-encoded string.

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.

Specify request headers and HTTP method in the Settings tab of the composer

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.

404 Not Found

  "error": {
    "message": "Unrecognized request URL. Please see 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 utilize 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:

Webhook error with the message "An active access token must be used to query information about the current user"

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

Braze will retry webhook sends for up to 24 hours. When retrying, Braze will make five attempts using exponential backoff for a period of approximately 30 minutes before aborting the individual webhook call.

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 parties servers. With IP allowlisting, you can verify that Webhooks requests are actually coming from Braze, adding an additional 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.

For Instances US-01, US-02, US-03, US-04, US-05, US-06, and US-07:
For Instances EU-01 and EU-02:
For Instance US-08:

Using webhooks with Braze partners

There are many ways to utilize webhooks, and with our technology partners (Alloys), you can use webhooks to level up your communication directly with your customers and users.

Check out:

New Stuff!