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. You can build your Data Transformation from default code, or by using our dedicated template library to help you get started with certain external platforms.

Prerequisites

Step 1: Identify a source platform

Identify an external platform you want to connect to Braze and check that the platform supports webhooks. These settings are sometimes 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

In the Braze dashboard, go to Data Settings > Data Transformation.

Select Create Transformation to name your transformation, then choose your editing experience.

Select Use a template to browse through a template library, including Data Transformation use cases. Or, select Start from scratch to load a default code template.

If you’re starting from scratch, choose a destination for your transformation. You can still insert a code template from the template library.

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.

Step 3: Send a test webhook (recommended)

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 the Braze dashboard 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.

• beginner - track users
• beginner - update catalog items
• advanced - track users

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;

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
53
// 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;

Step 5: Monitor your transformation

After activating your transformation, refer to the analytics on the main Transformations page for a performance summary.

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

Troubleshooting

For more detailed monitoring and troubleshooting, refer to the Logs page for specific logs, which is where the last 1,000 incoming requests to all transformations across your workspaces are logged. You can select each log to view the incoming request body, transformation output, and response body from the transformation’s destination.

If there are no deliveries, check your transformation code for any syntax errors and confirm that the code compiles. Then, check whether the output is a valid destination request.

Deliveries less than the number of incoming requests indicate 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.