Braze Tutorial: Use A Webhook To Log Test Custom Events

No more submitting engineering tickets or going deep inside your mobile app and entering a dummy credit card info to log a test custom event. As technical marketers, we get it done ourselves! 💪🏻

Youtube

❗️Check out the full tutorial on Youtube❗

https://youtu.be/W9_vgLegBVU?si=5npzXxxyiLv6bXyB

Objective

Custom events serve as the trigger event for many Braze Campaigns and Canvases, like Order Confirmation emails, User Signup Canvas Flows, the examples are endless.

That also means that whenever we need to QA our Braze setup, we need to be able to freely fire those custom events or those trigger events.

This Custom Event Webhook will be a highly useful tool for any team’s QA process.

Pain Points

No more submitting engineering tickets or going deep inside your mobile app and entering a dummy credit card info to log a test custom event. As technical marketers, we get it done ourselves! 💪🏻

This is potentially a huge time saver for many teams.

It was amazing to see our clients’ reaction after setting up this webhook template for them; not being able to log certain custom events for testing was a huge blocker for the team, and this webhook template just solved that problem.

Tutorial

So let’s get started! By the way, all tutorials will be in the new dashboard navigation.

First, let’s go to Templates → Webhook Templates → Create Webhook Template.

We’ll call this template “Users Track, Custom Event” since we’ll be using the Users Track API Endpoint to log a Custom Event.

You can also log profile attributes, custom attributes, and purchase events through this endpoint as well.

By the way, we’re using a Webhook Template and not a Webhook Campaign as we don’t need to launch a full campaign to log the test custom events and templates are easier to manage.

There are 3 parts when building a webhook:

1. Webhook URL

To figure out our full Webhook URL, we first need to look at our Braze Dashboard’s URL and look for the number and whether the root URL ends in .com or .eu.

This is your Braze server or Braze cluster. The numbers range from 01 to 08, and there are only US or EU servers. Examples: US01, US05, EU02, etc.

Once you’ve found your Braze server, go to Step 3a of this blog or copy one of the corresponding Webhook URLs below and insert into the Webhook URL field in your Webhook Template.

Everyone’s Webhook URL will be one of the URLs 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

And the Webhook URL is pretty much the “address” or the “destination” of this webhook.

The webhook now knows where to go, in our case, the EU02 server and the Users Track API endpoint, to make the data changes.

2. Request Body

This is the meat of the Webhook. We’re giving the webhook directions on what to do, what data to write, which user profile to write it to, etc.

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), we’ve found that it can’t quite get the job done.
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.

Copy and paste the code snippet below; this snippet will serve as the template code when we’re ready to use this webhook.

{
  "events": [
    {
      "external_id": "EXTERNAL_ID",
      "name": "CUSTOM_EVENT_NAME",
      "time": "T",
      "properties": {
        "property1": "value1",
        "property2": "value2"  
      }
    }  
  ]
}

A few details about the code:

• events: there’s the events object, attributes object, and purchase object, when using the Users Track endpoint. Since we’re logging a custom event, we use the events object.
• external_id: identifying the user profile by external_id. You can also search by user_alias or braze_id.
• name: name of the custom event
• time: every custom event requires a timestamp for when the event happened. In the code, we’re using Liquid’s special keyword “now” and some strftime syntax to turn the timestamp into the Braze-preferred ISO-8601 format which is the familiar YYYY-MM-DD, T for “time”, hh:mm:ss format.
• properties: metadata of the custom event or attributes that describe the specific occurence of this custom event; these do not count towards data points.

3. Request Headers

Under the settings tab, we need to add two Request Headers in the form of key-value pairs, also known as “KVPs”.

KVPs are literally a pair of a key and a value, and the two necessary Request Headers are the same for all Braze API calls:

• Content-Type: application/json
• Authorization: Bearer YOUR-API-KEY-1234-ABCD

The webhook is asking us, “What type of content are you providing?” and our answer or our value is “application/json”.

The wehbook is also asking, “What is your authorization?” and we provide the API key in our answer.

Let’s go ahead and copy and paste both for now, but we’ll need to create an actual, valid API key next.

API KEY

In a new tab, let’s open up Settings → API Keys → Create New API Key.

We’ll name this API Key “Users Track”.

When creating API keys, there are two best practices:

1. Only enable the endpoint that we need to use.

In our case, we only need the users.track endpoint, so let’s go ahead and enable this endpoint.

But you can also see the tons of other API endpoints that Braze offers, so definitely come back to this page to check out the other API capabilities.

For now, we’ll scroll to the bottom and click “Save API Key”.

2. Never expose or share your API keys.

API keys are highly sensitive, so we always want to be careful when using API keys. Please do not share your API keys with anyone!

Once the Users Track API Key is created, copy the API key, go back to the Settings tab of the Webhook Template, and replace the “YOUR-API-KEY-1234-ABCD”.

Your final value should look like “Bearer ACTUAL-API-KEY”. “ACTUAL-API-KEY” is your actual API Key, not the words “ACTUAL API KEY”. (😂)

Done!

At this point, we are finished creating our Webhook Template!

Go ahead and click “Save Template” so we don’t lose our progress.

Now, let’s put this awesome webhook template to use.

Click “Back to Templates” on the bottom left corner, click the settings gear on the right, and click “Duplicate”.

We’ll use our template to log a custom event called MEMBERSHIP_STARTED. We’ll name this webhook “Users Track, Custom Event, MEMBERSHIP_STARTED”.

There’s a few things we need to change to the code:

• external_id: we’ll use an external_id of the internal user profile that we’re testing with. Our internal external_id (a bit of an oxymoron) is “allan123”.
• name: instead of the generic “CUSTOM_EVENT_NAME”, we have to use the name of the test custom event that we’re logging which is MEMBERSHIP_STARTED
• time: stays the same. Best practice is to use the current timestamp.
• properties: you can log whichever properties you’d like, and if you’re testing for the correct rendering of the property values that’s templated in your messages, then make sure to use those properties. For example, if you’re rendering “membership_end_date” in this campaign that you’re sending which is triggered by MEMBERSHIP_STARTED, then you definitely want to include “membership_end_date” as a property so you can see how the message renders.

{
  "events": [
    {
      "external_id": "allan123",
      "name": "MEMBERSHIP_STARTED",
      "time": "T",
      "properties": {
        "membership_end_date": "2023-11-23",
        "membership_price": 99 
      }
    }  
  ]
}

“Send Test”

Finally, let’s go to the “Test” tab.

Before we click “Send Test”, please note that you’ll be making a real API call with this test.

It’s called a “test” in the sense that you’re making a one-off call and not launching to a whole batch of users, but you are still making a real API call with this webhook.

However, since we know exactly which user profile we’re writing to, which is allan123 in our case, we’re working within a controlled environment, so we know that it’s safe to go ahead and click “Send Test”.

If you see a “201 Created” message, that means the API call was a success!

If you see an error message that has the code 4-something-something, please try the steps once again, or please send us an email or reach out to me on Email Geeks Slack, and we’re happy to help.

Lastly, let’s navigate to Audience → Search Users → allan123, confirm the magic of this webhook template, see that MEMBERSHIP_STARTED was logged a few seconds ago, and we are finished!

Thank you!

To summarize, we created a Custom Event Webhook Template so we can log any custom event to any user profile, anytime we want, which will be tremendously helpful when we need to QA our Braze setup.

If you have any questions, please share them in the comments. We’re happy to help! 🙏

If you learned something from this tutorial, please subscribe for more awesome Braze tutorials in the future!

Thank you for reading, and see you next time!

allan@fornowmarketing.com

fornowmarketing.com