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 account with a promotion once they’ve performed a custom event a certain number of times.
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
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 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 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.
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.
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 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.
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.
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:
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?|
|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.
There are many ways to utilize webhooks, and with Braze’s technology partners (Alloys) you can use webhooks to uplevel your communication directly with your customers and users.