Braze Step-By-Step Guide: How to Create API Keys and Set Up Webhook Campaigns

Knowing how to use Braze Webhooks unlocks a whole new world of use cases. Read this step-by-step tutorial to get one step closer to becoming a Technical Marketer 💪🏻

My First API Call

I still remember my very first API call. We owed a customer a couple thousand dollars, but due to an internal error, the payment has been delayed for weeks, and the customer needed the funds ASAP. At the end of a heated, angry phone call, I told her, “We’ll get it to you by tomorrow.”

I had no idea how this was gonna get done.

“Desperate times call for desperate measures”; I considered sending the funds from my own bank via venmo/zelle or via an expedited check. Although it was past business hours, I messaged my CTO about the call, and he said “Lob has an overnight check delivery option via API.”

It was 7pm in the office (before COVID), and I’m frantically Googling multiple variations of “how to make an API call with Lob.” I had no idea where to start.

An old college friend — Computer Science major — to the rescue. He helped me step-by-step with creating a Python file, writing the API call, and running the script in Terminal. I had no idea what was going on; it was just “monkey see, monkey do” at that point.

Finally, I refreshed the Lob dashboard and saw a pending check in “overnight delivery” status; I had made my first API call.

Fast forward many years, I’m now making API calls everyday with Braze and excited to pay it forward with this blog. The good news is that the Braze Webhooks provide some level of UI support.

Let’s get into it!

Step 1: Decide Which API Endpoint to Use

Braze has a ton of different API endpoints, and they’re creating more everyday. You can see the full list here, but here are some very popular endpoints to help you get started:

• /users/track: updating user profiles with custom data; your team most likely uses this endpoint, hundreds of times per day
• /messages/send: sending a message via API without requiring any dashboard setup
• /users/export/ids: export user details by external_id or email address. Keep an eye out for a sweet use case with this endpoint.
• /email/bounce/remove: remove email addresses that incorrectly got included in the hard bounce list

By the way, if you’re not sure what an API endpoint is, here’s an analogy:

You call your favorite restaurant on a Friday night, and the Interactive Voice Response says, “Press 1 to hear our availability, Press 2 to make a reservation, Press 3 to connect to someone.”

Think of each of those options as an endpoint. Option 1 could be something like /reservations/export, option 2 could be something like /reservations/update, and option 3 could be something like /speak/human.

Step 2: Create an API Key with Permissions to the Desired Endpoint

Each API key you create can be enabled for specific API endpoints. The best practice is to:

• Only enable the specific endpoints that are intended for your use case
• Never, EVER share your API key with anyone. This would be the equivalent of you giving someone your Braze dashboard username/pw.

Go to Settings → API Key → Create New API Key.

Give it a specific name — like “User Update | Holiday Marketing | Allan” — check the desired endpoints, and save the API key.

Step 3: Webhook Setup

Sneak Peek: Final result looks like this.

Step 3a: Webhook URL

First, you’ll first have to find the REST ENDPOINT URL for your dashboard cluster. To do this, look at the URL of your Braze dashboard and find the matching root link from the URL column in the screenshot below. Your REST ENDPOINT will be the corresponding link in the REST ENDPOINT column.

For example, in the screenshot below, you’ll see that the root link of my Braze dashboard is https://dashboard-02.braze.eu/. Therefore, we know that my REST ENDPOINT URL is https://rest.fra-02.braze.eu.

Once you’ve found your REST ENDPOINT URL, you’ll have to add the specific API Endpoint we’re using. You can find this on every API Endpoint Documentation. Here’s an example below for the /users/track endpoint:

If you’re using the /users/track endpoint, the full Webhook URL should be one of the links below:

https://rest.iad-01.braze.com/users/track

https://rest.iad-02.braze.com/users/track

https://rest.iad-03.braze.com/users/track

https://rest.iad-04.braze.com/users/track

https://rest.iad-05.braze.com/users/track

https://rest.iad-06.braze.com/users/track

https://rest.iad-08.braze.com/users/track

https://rest.fra-01.braze.eu/users/track

https://rest.fra-02.braze.eu/users/track

See the Braze API Overview page for more details.

Step 3b: Request Body

This is probably the toughest part of the setup, and unfortunately, because the setup looks different for every endpoint, we won’t be able to cover all the endpoints in this blog.

However, once again, there are clear instructions and even example request bodies on every single endpoint documentation, so definitely check those out.

You do have 2 options for the Request Body:

1. JSON Key/Value Pairs: This option makes it easy to write the request body by providing a UI. However, for complicated request bodies (often times in /users/track), I’ve found that it can’t quite get the job done. However, the Email Preference Center Setup uses this route, so you can definitely go this route for some use cases.
2. Raw Text: The ultimate freedom. If option 1 is the Drag & Drop Editor, this would be the HTML Editor. Ability to freely write the JSON body. Warning: you could spend hours looking for one syntax mistake, like a missing comma.

In the example above, below is the request body we used to log a custom attribute called “test_attribute” to the user with external_id = “1” (me).

{
“attributes”: [
{
“external_id”:”1",
“test_attribute”: “test”
}
]
}

Step 3c: Settings

For EVERY, SINGLE, API CALL to Braze, you’ll need these Request Headers. Simply copy and paste these Key-Value Pairs, and you’re good to go. Of course, you’ll have to replace “YOUR_API_KEY” with your actual API key found in step 2.

Believe it or not, if you input “Bearer YOUR_API_KEY” in your webhook, your API call won’t work. 💀

Content-Type: application/json

Authorization: Bearer YOUR-API-KEY-1234-ABCD

Bonus Step: Send an API Call!

Although you’re officially done with your Webhook Setup, this is one of my favorite capabilities of Braze: being able to send a test API call from the dashboard.

If you navigate to the Test tab and click “Send Test”, this will actually send an API call based on your setup.

Keep in mind, this is actually a real API call; if we wanted to, we could technically send that overnight check via Lob with a Braze webhook.

It’s only called a “test” in the sense that this will be a single API call, most likely for you to make a one-off test before launching this campaign, and not blast a batch of API calls.

What we do is draft a handful of pre-filled Webhook campaigns for some API calls that we make often. This way, whenever weneed to make a quick API call, wecome back to these draft campaigns and make the API call using the test feature.

It’s simply replacing the need to use Postman to make calls, and we know that Postman, although it’s a super cool app, could be a daunting place with many, many buttons.

Conclusion

That’s it! These are the steps that are required to set up every single Braze-to-Braze Webhook (a webhook sent from Braze, to Braze API Endpoints).

We’ll be referring to this blog post every time we write another API use case guide in the future, so please feel free to read this multiple times to fully understand the setup process! And if there are any issues or questions, please let us know.

Thank you!

Thank you for reading, and please feel free to reach out with any questions.

fornowmarketing.com

allan@fornowmarketing.com