Skip to content

Creating a transformation

Braze Data Transformation enables you to build and manage webhook integrations to automate data flow from external platforms into Braze. These webhook integrations can then power even more sophisticated marketing use cases.

Prerequisites

Requirement Description
Two-factor authentication or SSO You must have two-factor authentication (2FA) or single sign-on (SSO) enabled for your account.
Correct permissions You must be either an account admin or a workspace admin, or have “Manage Transformations” user permissions.

Step 1: Identify a source platform

Identify an external platform you want to connect to Braze and check that the platform supports webhooks. Sometimes, these settings are referred to as “API notifications” or “web service requests”.

The following is an example Typeform webhook, which is configurable by logging into their platform:

Step 2: Create a transformation

Navigate to the Braze dashboard, and go to Data Settings > Data Transformation.

Click Create Transformation to name your transformation, then choose a destination.

More on destinations
  • POST: Track users: Transforms webhooks from a source platform into user profile updates, such as attributes, events, or purchases.
  • PUT: Update multiple catalog items: Transforms webhooks from a source platform into catalog item updates.
  • DELETE: Delete multiple catalog items: Transforms webhooks from a source platform into catalog item deletions.
  • PATCH: Edit multiple catalog items: Transforms webhooks from a source platform into catalog item edits.

After creating your transformation, you’ll see the detailed view of the transformation. Here, you can view the most recent webhook received for this transformation under Webhook details and a space to write your transformation code under Transformation code.

This step is optional, but we recommend sending a test webhook from your source platform to your newly created transformation.

  1. Copy the URL from your transformation.
  2. In your source platform, find a “Send Test” capability to have it generate a sample webhook to send over to this URL.
    • If your source platform prompts for a request type, select POST.
    • If your source platform provides authentication options, select No authentication.
    • If your source platform asks for secrets, select No secrets.
  3. Refresh your page in Braze to see if the webhook has been received. If it was received, you should see a webhook payload under “Most recent webhook”.

Here’s what it looks like for Typeform:

Step 4: Write transformation code

If you have little to no experience with JavaScript code or prefer more detailed instructions, follow the Beginner - POST: Track users or Beginner - PUT: Update multiple catalog items tab for writing your transformation code.

If you’re a developer or have significant experience with JavaScript code, follow the Advanced - POST: Track users tab for high-level instructions on writing your transformation code.

Here, you will write transformation code to define how you’d like to map various webhook values to Braze user profiles.

  1. New transformations will include this default template in the Transformation Code section: 
    1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

     // Here, we will define a variable, "brazecall", to build up a `/users/track` request
 // Everything from the incoming webhook is accessible via the special variable "payload"
 // So you can template in desired values in your `/users/track` request with dot notation, such as payload.x.y.z

 let brazecall = {
    "attributes": [
     {
       "external_id": payload.user_id,
       "_update_existing_only": true,
       "attribute_1": payload.attribute_1
     }
   ],
   "events": [
     {
       "external_id": payload.user_id,
       "_update_existing_only": true,
       "name": payload.event_1,
       "time": new Date(),
       "properties": {
         "property_1": payload.event_1.property_1
       }
     }
   ],
   "purchases": [
     {
       "external_id": payload.user_id,
       "_update_existing_only": true,
       "product_id": payload.product_id,
       "currency": payload.currency,
       "price": payload.price,
       "quantity": payload.quantity,
       "time": payload.timestamp,
       "properties": {
         "property_1": payload.purchase_1.property_1
       }
     }
   ]
 };

 // After the/users/track request is assigned to brazecall, you will want to explicitly return brazecall to create an output
 return brazecall;
  2. If you’d like all three (custom attributes, custom events, and purchases) in your transformation calls, skip to step 3. Otherwise, delete the sections that you don’t need.

  3. Each attribute, event, and purchase object requires a user identifier, either an external_id, user_alias, braze_id, email, or phone. Find the user identifier in the incoming webhook’s payload, and template in that value in your transformation code via a payload line. Use dot notation to access payload object properties.

  4. Find the webhook values you’d like to represent as attributes, events, or purchases, and template those values in your transformation code via a payload line. Use dot notation to access payload object properties.

  5. For each attribute, event, and purchase object, examine the _update_existing_only value. Set this to false if you want the transformation to create a new user that may not exist. Leave this as true to only update existing profiles.

  6. Click Validate to return a preview of your code’s output and to check if it is an acceptable /users/track request.

  7. Activate your transformation. For additional help with your code before activating it, contact your Braze account manager.

  8. Have your source platform begin sending webhooks. Your transformation code will run for each incoming webhook, and user profiles will begin updating.

Your webhook integration is now complete!

Here, you will write transformation code to define how you’d like to map various webhook values to Braze catalog item updates.

  1. New transformations will include this default template in the Transformation Code section: 
    1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52

     // This is a default template that you can use as a starting point
 // Feel free to delete this entirely to start from scratch, or to edit specific components
    
 // First, this code defines a variable, "brazecall", to build a PUT /catalogs/{catalog_name}/items request
 // Everything from the incoming webhook is accessible via the special variable "payload"
 // As such, you can template in desired values in your request with JS dot notation, such as payload.x.y.z
    
 let brazecall = {
 // For Braze Data Transformation to update Catalog items, the special variable "catalog_name" is required
 // This variable is used to specify the catalog name which would otherwise go in the request URL
 "catalog_name": "catalog_name",
 // After defining "catalog name", construct the Update Multiple Catalog Items request as usual below
 // Documentation for the destination endpoint: https://www.braze.com/docs/api/endpoints/catalogs/catalog_items/asynchronous/put_update_catalog_items/
 "items": [
   {
     "id": payload.item_id_1,
     "catalog_column1": "string",
     "catalog_column2": 1,
     "catalog_column3": true,
     "catalog_column4": "2021-09-03T09:03:19.967+00:00",
     "catalog_column5": {
       "Latitude": 33.6112,
       "Longitude": -117.8711
     }
   },
   {
     "id": payload.item_id_2,
     "catalog_column1": "string",
     "catalog_column2": 1,
     "catalog_column3": true,
     "catalog_column4": "2021-09-03T09:03:19.967+00:00",
     "catalog_column5": {
       "Latitude": 33.6112,
       "Longitude": -117.8711
     }
   },
   {
     "id": payload.item_id_3,
     "catalog_column1": "string",
     "catalog_column2": 1,
     "catalog_column3": true,
     "catalog_column4": "2021-09-03T09:03:19.967+00:00",
     "catalog_column5": {
       "Latitude": 33.6112,
       "Longitude": -117.8711
     }
   }
 ]
 };
    
 // After the request body is assigned to brazecall, you will want to explicitly return brazecall to create an output
 return brazecall;
  2. Transformations for /catalogs destinations require a catalog_name to define the specific catalog that you’d like to update. You can hard code this field, or template the field with a webhook field via a payload line. Use dot notation to access payload object properties.

  3. Define which items you’d like to update in the catalog with the id field(s) in the items array. You can hard code these fields, or template in a webhook field via a payload line.

    Keep in mind, “catalog_column” is a placeholder value. Be sure item objects only contain fields that exist in the catalog.

  4. Click Validate to return a preview of your code’s output and to check if it is an acceptable request for the Update multiple catalog items endpoint.

  5. Activate your transformation. For additional help with your code before activating it, contact your Braze account manager.

  6. Make sure to check if your source platform has a setting to start sending webhooks. Your transformation code will run for each incoming webhook, and the catalog items will begin updating.

Your webhook integration is now complete!

In this step, you will transform the webhook payload from the source platform to a JavaScript object return value. This return value must adhere to Braze’s /users/track request body format:

  • Transformation code is accepted in the JavaScript programming language. Any standard JavaScript control flow, such as if/else logic, is supported.
  • Transformation code accesses the webhook request body via the payload variable. This variable is an object populated by parsing the request body JSON.
  • Any feature supported in our /users/track endpoint is supported, including:
    • User attributes objects, event objects, and purchase objects
    • Nested attributes and nested custom event properties
    • Subscription group updates
    • Email address as an identifier

Click Validate to return a preview of your code’s output and to check if it’s an acceptable /users/track request.

Step 5: Monitor your transformation

After activating your transformation, refer to the analytics on the main Transformations page for a high level view of its performance.

  • Incoming Requests: This is the number of webhooks received at this transformation’s URL. If incoming requests are 0, your source platform hasn’t sent over any webhooks, or the connection cannot be made.
  • Deliveries: After receiving incoming requests, Data Transformation applies your transformation code to send to your selected Braze destination.

It’s a good goal to have 100% of incoming requests leading to deliveries. The number of deliveries will never exceed the number of incoming requests.

For more detailed monitoring and troubleshooting, refer to the Logs page for specific logs. This is where the last 1,000 incoming requests to all transformations across all workspaces are logged. You can click each log to view the incoming request body, transformation output, and response body from the transformation’s destination. You can use these details to troubleshoot any errors.

Troubleshooting

  • If deliveries are 0, check your transformation code to ensure there are no syntax errors and that it compiles. Then, check whether the output is a valid destination request.
  • If deliveries are less than the number of incoming requests, this indicates that at least some webhooks are delivered successfully. Refer to transformation logs for example errors, and look to see if the transformation output is expected. It’s possible that your transformation code is not accounting for every variation of webhooks received.
  Edit this page on GitHub
HOW HELPFUL WAS THIS PAGE?
New Stuff!