Creating a Braze-to-Braze webhook

You can use webhooks to communicate with the Braze REST API, essentially doing anything that our API allows you to do. We refer to this as a Braze-to-Braze webhook—a webhook that is communicating from Braze to Braze. The use cases on this page assume that you’re familiar with how webhooks work and how to create a webhook in Braze.

Prerequisites

To create a Braze-to-Braze webhook, you’ll need an API key with permissions for the endpoint you want to reach.

Setting up your Braze-to-Braze webhook

While the specifics of your webhook request will vary from use case to use case, the general workflow for creating a Braze-to-Braze webhook stays the same.

1. Create a webhook as a campaign or Canvas component.
2. Choose Blank Template.
3. In the Compose tab, specify the Webhook URL and Request Body as noted for your use case.
4. In the Settings tab, specify your HTTP Method and Request Headers as noted for your use case.
5. Continue to build out the rest of your webhook as needed. Some use cases require specific delivery settings, such as triggering the campaign or Canvas from a custom event.

Use cases

While there’s a lot you can do with Braze-to-Braze webhooks, here are some use cases to get you started:

• Increment an integer custom attribute for a counter when a user receives a message.
• Trigger a second Canvas from an initial Canvas.

Use case: Increment an integer custom attribute for a counter

This use case involves creating a custom attribute and using Liquid to count the number of times a specific action has occurred.

For example, you might want to count how many times a user has seen an active in-app message campaign and prevent them from receiving the campaign again after they’ve seen it three times. For more ideas on what you can do with Liquid logic in Braze, check out our Liquid use case library.

Follow the general steps for creating a Braze-to-Braze webhook, and refer to the following when configuring your webhook:

• Webhook URL: Your REST endpoint URL followed by /users/track. For example, for the US-06 instance, the URL would be https://rest.iad-06.braze.com/users/track.
• Request Body: Raw Text

Request headers and method

Braze requires an HTTP header for authorization that includes your API key and another that declares your content-type.

• Request Header:
  • Authorization: Bearer {YOUR_API_KEY}
  • Content-Type: application/json
• HTTP Method: POST

Replace YOUR_API_KEY with a Braze API key with users.track permissions. You can create an API key within the Braze dashboard at Settings > API Keys.

Request body

Add your user track request in the request body and the Liquid to assign a counter variable. For more details, refer to the /users/track endpoint.

The following is an example of both the required Liquid and request body for this endpoint, where your_attribute_count is the attribute you’re using to count how many times a user has seen a message:

1
2
3
4
5
6
7
8
9
{% assign new_number = {{custom_attribute.${your_attribute_count}}} | plus: 1 %}
{
    "attributes": [
        {
        "external_id": "{{${user_id}}}",
        "your_attribute_count": "{{new_number}}"
        }
    ]
}

Use case: Trigger a second Canvas from an initial Canvas

For this use case, you’ll create two Canvases and use a webhook to trigger the second Canvas from the first Canvas. This acts like an entry trigger for when a user reaches a certain point in another Canvas.

1. Start by creating your second Canvas—the Canvas that should be triggered by your initial Canvas.
2. For the Canvas Entry Schedule, select API-Triggered.
3. Make note of your Canvas ID. You’ll need this in a later step.
4. Continue building out the steps of your second Canvas, then save the Canvas.
5. Finally, create your first Canvas. Find the step where you want to trigger the second Canvas and create a new step with a webhook.

Refer to the following when configuring your webhook:

• Webhook URL: Your REST endpoint URL followed by canvas/trigger/send. For example, for the US-06 instance, the URL would be https://rest.iad-06.braze.com/canvas/trigger/send.
• Request Body: Raw Text

Request headers and method

Braze requires an HTTP header for authorization that includes your API key and another that declares your content-type.

• Request Header:
  • Authorization: Bearer YOUR_API_KEY
  • Content-Type: application/json
• HTTP Method: POST

Replace YOUR_API_KEY with a Braze API key with canvas.trigger.send permissions. You can create an API key within the Braze dashboard at Settings > API Keys.

Request body

Add your canvas/trigger/send request in the text field. For more details, refer to Sending Canvas messages via API-triggered delivery. The following is an example of the request body for this endpoint, where your_canvas_id is the Canvas ID from your second Canvas:

1
2
3
4
5
6
7
8
{
      "canvas_id": "your_canvas_id",
      "recipients": [
        {
          "external_user_id": "{{${user_id}}}"
         }
      ]
}

Things to know

• Braze-to-Braze webhooks are subject to endpoint rate limits.
• Updates to the user profile will incur additional data points, while triggering another message through the messaging endpoints will not.
• If you want to target anonymous users, you can use braze_id instead of external_id in the request body of your webhook.
• You can save your Braze-to-Braze webhook as a template to be used again.
• You can check the Message Activity Log to view and troubleshoot webhook failures.