Send Custom Audience to Facebook through webhooks

Note: Completing this procedure requires some knowledge on sending API requests using cURL, Postman, or simlar tools.

You can use Automation to send a Custom Audience (segment of people) from Synerise to Facebook.

Alternative way of sending Custom Audience

The easiest way to do so is to send an event to Facebook Pixel using dynamic content. However, this solution is suitable only for continuously sending the customers who visit your website to the Custom Audience. If you do not want to rely on the website and you just want to immediately send a group of customers to Facebook, then you can use Automation and Facebook API.

Full documentation about Custom Audiences in Facebook.

Process overview


To send Custom Audience, follow the steps listed below in the following order:

  1. Authorize in Facebook Ad
  2. Create an empty Custom Audience
  3. Test your Custom Audience
  4. Create a schema
  5. Create an outgoing integration
  6. Create a workflow

Authorize in Facebook Ad


In this part of the process, you add a System User, grant this user access to your ad account, and create a System User Access token.

Tip: This step is performed on your Facebook Ad account. If you’re not familiar with the Facebook Ad user interface, you can read its documentation here.
  1. Go to your account in Facebook Ad > Business Manager > Business Settings.
  2. Select System Users.
  3. Click Add New System User.
    Result: A user is added.
  4. As the role for the new user, select Admin System User.
  5. Grant your new user access to your ad account.
    1. Go to Business Manager > Business Settings.
    2. Select System Users.
    3. Select the new user and click Assign Assets.
    4. Select your ad account.
      Result: The user has access to your ad account.
  6. Go to Business Manager > Business Settings.
  7. Select System Users.
  8. Select the new user and click Generate New Token.
  9. Go to Your app > For scope, select ads_management.
  10. Copy your token, paste it to the notepad for use in the next steps.
    Important: Save the token because it won’t be accessible later. Such token never expires.

Create an empty Custom Audience


In this part of the process, you must create a Custom Audience. You can do it in two ways:

  1. You can do it directly on the interface on your Facebook Ad account.
  2. You can do it through API (send a request to Facebook API to get the ID of the Custom Audience).
using Facebook interface

Go to your Facebook Ad account and create a Custom Audience. After you create it, note down its ID.

using API

  1. Open a tool that sends API requests (for example, Postman).
  2. Create a request. It must contain the ID of the ad account in which Custom Audience is used.
    Tip: Full documentation of Custom Audiences in Facebook.
  3. In response of such request you receive ID of the Custom Audience. You will need it in the next steps.
curl --location --request POST 'https://graph.facebook.com/v7.0/act_{{AD_ACCOUNT_ID}}/customaudiences' \
--form 'access_token={{ACCESS_TOKEN}}' \
--form 'name={{NAME_OF_CUSTOM_AUDIENCE}}' \
--form 'subtype=CUSTOM' \
--form 'description={{SOME_DESCRIPTION_HERE}}' \
--form 'customer_file_source=USER_PROVIDED_ONLY'

Test your Custom Audience


In this part of the process, you must test whether the Custom Audience you created accepts customers.

  1. You can use Postman to send a test call.
    Note: The structure of this test call will be reused in the request body in one of the Outgoing integration node in the Create an automation.
  2. In the request, you must provide the ID of the Custom Audience received from the request you prepared in the Create an empty Custom Audience step.
  3. Include the data array and provide there a user email encoded in SHA256 algorithm.
    Note: For this test you can use external tools to encode an email in SHA256 algorithm. In the further steps you will create a webhook that automatically encodes emails.
    Result: If the Custom Audience works, you receive a HTTP 200 response with "num_received": 1 in the body.
Example test call

curl --location --request POST 'https://graph.facebook.com/v9.0/{{ID_OF_CUSTOM_AUDIENCE}}/users?access_token={{ACCESS_TOKEN}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "payload": { 
    "schema": [ 
      "EMAIL" 
    ], 
    "data": [ 
      [ 
        "3526a0b95cb0cbe97662cc7d91765fc5a89bd30310725f9373e09d8cf8683d4d" 
      ]
    ] 
  }
}'

Tip: Check the Facebook documentation to get more details.

Create a schema


In this part of the process, you must create a schema that you will use in the outgoing integration, which you will prepare in the next step. The schema must include three fields that will pass the following information:

  • the ID of the Custom Audience in Facebook (a text field)
  • the type of customer’s identifier (a selector)
  • the customer identifier encoded using SHA-256 (a text field)
Note: You can find more information about Schema Builder here.
  1. Go to Assets > Schema Builder > New schema.

  2. Enter the name of the schema (for example, Facebook Audience).

  3. Drag the Text input component to the schema structure.

  4. Click the text input and then click Pencil icon.

  5. In the Label field, enter the name of text input which is Audience ID.

    The Audience node configuration
    The configuration of the Audience ID field
  6. Drag the Select component to the schema structure.

  7. Click Pencil icon.

  8. In the Label field, enter the name of the select component, for example Type of identifier.

    The Audience node configuration
    The configuration of the ID type selector
    1. Go to the Data tab, enter the labels and values for selector options (see screenshot).
    The Audience node configuration
    The configuration of the ID type selector
  9. Drag the Text input component to the schema structure.

  10. Click Pencil icon.

    1. In the Field Id, enter the identifier of the field in the schema.
    2. In the Label field, enter the visible name of the field, for example identifier.
    The Audience node configuration
    The configuration of the Identifier field
  11. Save the schema.

    Preview of schema
    Schema preview

Create an outgoing integration


In this part of the process, you prepare an outgoing integration that sends customers from Synerise to Custom Audience in Facebook. The integration is built based on the schema you prepared in the previous part of the process.

The outgoing integration will contain inserts which will refer to the fields in schema and retrieve the values from these fields.

  1. Go to Automation > Outgoing > New integration.

  2. Enter the name of the integration.

  3. In the Define section:

    1. Select the POST method.
    2. Enter the endpoint (you can find it in the Facebook documentation).
    3. Replace the ID of the Custom Audience with {% context text-input %}.
      For example, in https://graph.facebook.com/v9.0/12345678910111213/users?access_token=, 12345678910111213 must be replaced with {% context text-input %}
    4. Enter the name of the event that will be generated when this integration takes place (for example, webhook.response).
    5. Click Apply.
    Settings of Outgoing integration
    Endpoint settings of the Outgoing integration
  4. In the Parameters section, from the dropdown list, select the schema you created in the Create a schema step.

    Settings of Outgoing integration
    Template of the Outgoing integration
  5. In the Webhook payload, enter the following code:

        {
        "payload": { 
        "schema": [ 
            "{% context select-field %}"
        ], 
        "data": [ 
            [ 
            "{% context identifier %}" 
            ]
          ] 
         }
        }
        

    The values for the select-field and identifier tags are retrieved from the event (the Outgoing integration) included in the workflow which you will create in the next part of the process:

    Preview of schema
    Schema preview
  6. Leave the rest of settings at default.

    Payload of the webhook
    Webhook payload
  7. Take the ID of your test Custom Audience and a test user’s phone or email address encoded into SHA-256 algorithm from the test call you performed in Test your Custom Audience step. You will need them in step 9.

    Example test call

    curl --location --request POST 'https://graph.facebook.com/v9.0/{{ID_OF_CUSTOM_AUDIENCE}}/users?access_token={{ACCESS_TOKEN}}' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "payload": { 
        "schema": [ 
          "EMAIL" 
        ], 
        "data": [ 
          [ 
            "3526a0b95cb0cbe97662cc7d91765fc5a89bd30310725f9373e09d8cf8683d4d" 
          ]
        ] 
      }
    }'

  8. Click Build test.

  9. On the pop-up, fill in the fields. It’s necessary to test if the integration works. If the test is successful, your integration is active.

    Testing the integration
    Testing the integration

Create a workflow


Tip: You can prepare a test workflow based on the instructions in this step for a group of test users.

In this step, create a workflow for a defined group of customers. Through the outgoing integraton the system sends the customers to Custom Audience in Facebook

Important: While sending the customers through the outgoing integration, the customer identifiers are encoded using SHA-256.
Context switch in a workflow
The Send customers to Custom Audience in Facebook automation

1. Choose customers

You can use any criteria to filter out the customers you want to send to Custom Audience.

  1. Go to Automation icon Automation > Workflows > New workflow.
  2. On the dashboard, click the plus icon.
  3. From the dropdown list, select Audience.
    Results: The Audience node is added to the dashboard.
  4. Double-click the node.
    Result: A pop-up appears.
  5. Leave the Run trigger option at default.
  6. Select an existing segment or segments of customers or create a new one.
    Tip: You can read more on creating segments in the Audience node.
  7. When the segment is chosen/prepared, click Apply.
The Audience node configuration
The Audience node configuration

2. Add Outgoing Integration

  1. Double-click the Outgoing integration node.
  2. From the select custom action dropdown list, choose the outgoing integration you created in the Create an outgoing integration step.
  3. In the Audience ID field, enter the ID of the Custom Audience to which you want to send your group of customers.
  4. From the Type of identifier dropdown list, select EMAIL.
  5. In the Identifier field, enter the following Jinjava code: {{ client.email | hash("SHA-256") }}
    Tip: You can also select phone instead of an email. In this case, in step 4, from the dropdown list, select PHONE. In step 5, in the Identifier field, enter the following Jinjava code:{{ client.phone | hash("SHA-256") }}
  6. Confirm by clicking Apply.
    The Client Filter nodes added
    The configuration of the Outgoing integration node

3. Add the End node

  1. On the Outgoing Integration node, click the plus icon.
  2. From the dropdown list, select End.
  3. In the upper right corner, click Save & Run.
    Result: On the customers’ profiles in Profiles, you can see the webhook.response events with 200 status and "num_received": 1 in the response bodies.
  4. Go to Facebook, Facebook Manager > Audiences to check your Custom Audience.
A webhook response with 200 status on a profile of a test customer
A webhook response with the OK status (200) on a customer's profile

Other variants of the workflow


You can build your workflow, so it can:

  • Send a group of customers to Custom Audience in Facebook only once.
  • Continuously send customers to Custom Audience in Facebook.

Example scenarios


Repeatable workflow using encoded email address

Context switch in a workflow
The Send customers to Custom Audience in Facebook automation

1. Choose customers

You can use any criteria to filter out the customers you want to send to a Custom Audience.

  1. Go to Automation icon Automation > Workflows > New workflow.
  2. On the right side of the screen, click Set capping.
    Result: A pop-up appears.
  3. On the pop-up, set the limit: 1 time in 180 months.
    Explanation: This way, this automation will be triggered only once in 15 years for a customer no matter how many times during this period the customer meets the conditions of the trigger. 15 years is the longest time to store the data about customer in the database.
  4. Confirm by clicking Apply.
  5. On the dashboard, click the plus icon.
  6. From the dropdown list, select Audience.
    Results: The Audience node is added to the dashboard.
  7. Double-click the node.
    Result: A pop-up appears.
  8. Set the Run trigger option to repeatable.
  9. In the Interval field, define the frequency of launching the trigger.
  10. In the Begin at field, define the first launch of the trigger.
  11. Add an audience in one of the following ways:
    • Select an existing segment or segments of customers.
    • Create a new segment.
    Tip: You can read more on creating segments in the Audience node.
  12. When the segment is chosen/prepared, click Apply.
The Audience node configuration
The Audience node configuration

2. Add Client Filter

  1. On the Audience node, click the plus button.
  2. From the dropdown list, select Client Filter.
    Result: A node appears on the dashboard.
  3. Double-click the Client Filter node.
    Result: A pop-up appears.
  4. On the pop up, click Choose filter.
    Result: A dropdown list appears.
  5. Select the Clients tab.
  6. From the list, select Attributes.
  7. Select Email address.
  8. From the Choose operator dropdown list, select Regular expression.
  9. In the text field, enter . which means that the value of the parameter is anything except for null.
    Result:
    The Client Filter node configuration
    The has email Client Filter node configuration
  10. Confirm by clicking Apply.
  11. On the Client Filter node, click the plus icon.
  12. From the dropdown list, select Outgoing Integration.
    Result: A matched path appears on the dashboard.
  13. On the Client Filter node, click the plus icon.
  14. From the dropdown list, select End.

3. Add Outgoing Integration

  1. Double-click the Outgoing integration node.
  2. From the select custom action dropdown list, choose the outgoing integration you created in the Create an outgoing integration step.
  3. In the Audience ID field, enter the ID of the Custom Audience to which you want to send your group of customers.
  4. From the Type of identifier dropdown list, select EMAIL.
  5. In the Identifier field, enter the following Jinjava code: {{ client.email | hash("SHA-256") }}
  6. Confirm by clicking Apply.
    The Client Filter nodes added
    The configuration of the Outgoing integration node

4. Add the End node

  1. On the Outgoing Integration node, click the plus icon.
  2. From the dropdown list, select End.
  3. In the upper right corner, click Save & Run.
    Result: On the customers’ cards in Profiles, you can see the webhook.response events with 200 status and "num_received": 1 in the response bodies.
  4. Go to Facebook, Facebook Manager > Audiences and check your Custom Audience.

One-time workflow using encoded email address or phone number

The repeatable automation that works based either on encoded email or phone number
The one-time workflow that works based either on encoded email or phone number

You can create a workflow that is launched for a selected group of customers. During the process, the system checks whether customers have either a phone number or an email address assigned. If so, through the outgoing integraton the system sends the customers to Custom Audience in Facebook.

1. Choose a group of customers

  1. Go to Automation icon Automation > Workflows > New workflow.
  2. On the dashboard, click the plus icon.
  3. From the dropdown list, select Audience.
    Results: The Audience node is added to the dashboard.
  4. Double-click the node.
    Result: A pop-up appears.
  5. Leave the Run trigger option at default.
  6. Choose a segment of customers or create a segment from scratch.
  7. When the segment is chosen/prepared, click Apply.
The Audience node
The configuration of the Audience node

2. Add the filters

The filters check if the customer has an email address or phone number (or both) in their profile. If not, the automation ends for that customer.

Adding the “has email?” filter

  1. On the Audience node, click the plus button.
  2. From the dropdown list, select Client Filter.
    Result: A node appears on the dashboard.
  3. Double-click the Client Filter node.
    Result: A pop-up appears.
  4. On the pop up, click Choose filter.
    Result: A dropdown list appears.
  5. Select the Clients tab.
  6. From the list, select Attributes.
  7. Select Email address.
  8. From the Choose operator dropdown list, select Regular expression.
  9. In the text field, enter . which means that the value of the parameter is anything except for null.
    Result:
    The Client Filter node configuration
    The has email Client Filter node configuration
  10. Confirm by clicking Apply.
  11. On the Client Filter node, click the plus icon.
  12. From the dropdown list, select Outgoing Integration.
    Result: A matched path appears on the dashboard.

Adding the “has phone?” filter

  1. On the Client Filter node, click the plus button.
  2. From the dropdown list, select Client Filter.
    Result: A not matched path appears on the dashboard.
  3. Double-click the Client Filter you have just added.
    Result: A pop-up appears.
  4. On the pop up, click Choose filter.
    Result: A dropdown list appears.
  5. Select the Clients tab.
  6. From the list, select Attributes.
  7. Select Phone.
  8. From the Choose operator dropdown list, select Regular expression.
  9. In the text field, enter . which means that the value of the parameter is anything except for null.
    Result:
    The Client Filter node configuration
    The has phone Client Filter node configuration
  10. Confirm by clicking Apply.
  11. On the “has phone” Client Filter node, click the plus icon,
  12. From the dropdown list, select Outgoing Integration.
    Result: A matched path appears on the dashboard.
  13. On the “has phone” Client Filter node, click the plus icon.
  14. From the dropdown list, select End.
    Result: A not matched path appears on the dashboard.
    The Client Filter nodes added
    The Client Filter nodes added

3. Add outgoing integration (after has email filter)

  1. Double-click the Outgoing integration node.
  2. From the select custom action dropdown list, choose the outgoing integration you created in the Create an outgoing integration step.
  3. In the Audience ID field, enter the ID of the Custom Audience to which you want to send your group of customers.
  4. From the Type of identifier dropdown list, select EMAIL.
  5. In the Identifier field, enter the following Jinjava code: {{ client.email | hash("SHA-256") }}
  6. Confirm by clicking Apply.
    The Client Filter nodes added
    The configuration of the Outgoing integration node

4. Add outgoing integration (after has phone filter)

  1. Double-click the Outgoing integration node.
  2. From the select custom action dropdown list, choose the outgoing integration you created in the Create an outgoing integration step.
  3. In the Audience ID field, enter the ID of the Custom Audience to which you want to send your group of customers.
  4. From the Type of identifier dropdown list, select EMAIL.
  5. In the Identifier field, enter the following Jinjava code: {{ client.phone | hash("SHA-256") }}
  6. Confirm by clicking Apply.
    The Client Filter nodes added
    The configuration of the Outgoing integration node

5. Add the End nodes

  1. Click the plus icon on the Outgoing Integration nodes.
  2. From the dropdown list, select End.
  3. In the upper right corner, click Save & Run.
    Important: Wait a few minutes for the response of the webhook.

Result: An automation event is saved to the profiles of the customers. Then, go Facebook, to Facebook Manager > Audiences to check your Custom Audience.

A webhook response with 200 status on a profile of a test customer
A webhook response with the OK status (200) on a customer's profile

😕

We are sorry to hear that

Thank you for helping improve out documentation. If you need help or have any questions, please consider contacting support.

😉

Awesome!

Thank you for helping improve out documentation. If you need help or have any questions, please consider contacting support.