Send Custom Audience through webhooks

Note: Completing this procedure requires some knowledge on sending API requests using tools such as curl or Postman.

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.

Requirements


Contact the Synerise Support or your project supervisor to get the internal endpoint for hashing a selected customers’ identifier.

Procedure


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 an automation to test webhook
  5. Create an automation

Authorize in Facebook Ad


In this step, 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. Select Admin System User as the role for the system user.
  5. Grant your system user access to your ad account.
  6. Go to Business Manager > Business Settings.
  7. Select System Users.
  8. Select the system user and click Assign Assets.
  9. Select your ad account.
    Result: The user has access to your ad account.
  10. Go to Business Manager > Business Settings.
  11. Select System Users.
  12. Select the system user and click Generate New Token.
  13. Go to Your app > For scope and select ads_management.
  14. Copy your token for the further steps and paste it to the text editor.
    Important: Save the token, because it won’t be accessible later. The token is permanent and it never expires.

Create an empty Custom Audience


In this step, 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).
via Facebook interface

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

via 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 step, 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 webhooks 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/v7.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 an automation to test the webhook encoding customers’ identifiers


In this step, you create a test automation, so you can check if the webhook that encodes customers’ identifier - it can be an email address or a phone number (in this procedure an email address is used) into SHA256 works properly. This step is optional.

Click to see an example automation that uses email addresses and phone numbers

The repeatable automation that works based either on encoded email or phone number
The repeatable automation that works based either on encoded email or phone number

1. Choose a test user

  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 test user or a segment of test users.
  7. When the segment is chosen/prepared, click Apply.
    Click here to see the configuration of the node

    The Audience node
    The configuration of the Audience node

2. Create a webhook that encodes customer’s ID into SHA256

  1. On the Audience node, click the plus icon .
  2. From the dropdown list, select Outgoing webhook.
    Result: The Ougoing webhook appears on the dashboard after the Audience node.
  3. Double-click the Outgoing webhook node.
    Result: A pop-up appears.
  4. On the pop-up, select the Custom webhook tab.
  5. In the action name, enter the name of an event that appears on the customer’s profile event list when the action defined in the webhook is executed (for example, get email Hash).
    Tip: If you want to encode a phone number, enter get phone Hash instead of get email Hash.
  6. Leave the method at default (POST).
  7. In the URL field, enter the endpoint you requested from the Synerise Support team.
  8. Set the content-type header to application/json (default).
  9. In the request body, enter "name": "{{ client.email }}".
    Tip: To encode a phone number, replace "name": "{{ client.email }}" with "name": "{{ client.phone }}".
  10. Leave the Authorization section at default.
  11. Confirm by clicking Apply.
    Click here to see the configuration of the node

    The Outgoing webhook node configuration
    The configuration of the webhook node that encodes an email

3. Add the End node

  1. Click the plus icon on the Outgoing webhook node.
  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.
The test automation
The test automation

Result: An automation event is saved to the CRM profiles of the test customers.

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

Create an automation


In this step, build the final automation. It reuses a customer’s identifier, which as a part of the automation is encoded into SHA256 (it can be email address, phone number, and so on). The encoded identifier is necessary for sending the group of customers to a Custom Audience created in Facebook, which also happens as a part of this automation.

You can build your automation, so it can:

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

Your automation can also reuse one or more types of ID, which is described in the Repeatable automation using either encoded email or phone section below.

Example scenarios


One-time automation 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 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. Create a webhook that encodes email into SHA256

  1. On the Audience node, click the plus icon.
  2. From the dropdown list, select Outgoing webhook.
    Result: The Ougoing webhook appears on the dashboard after the Audience node.
  3. Double-click the Outgoing webhook node.
    Result: A pop-up appears.
  4. On the pop-up, select the Custom webhook tab.
  5. In the action name, enter the name of the event that will appear on the customer’s profile event list, when the action defined in the webhook is executed (for example, get email Hash).
  6. Leave the method at default (POST).
  7. In the URL field, enter the endpoint you requested from the Synerise Support team.
  8. Set the content-type header to application/json (default).
  9. In the request body, enter "name": "{{ client.email }}".
    Tip: To encode a phone number, replace {{ client.email }} with {{ client.phone }}.
  10. Leave the Authorization section at default.
  11. Confirm by clicking Apply.
The Outgoing webhook node configuration
The configuration of the webhook node that encodes an email hash

3. Wait for the email hash to be generated

This node checks if the email addresses are encoded into SHA256.

  1. On the Outgoing webhook node, click the plus icon .
  2. From the dropdown list, select Client Event Filter.
    Result: The Client Event Filter appears on the dashboard, after the Outgoing webhook node.
  3. Double-click the Client Event Filter node.
    Result: A pop-up opens.
  4. Leave the Check option at default.
  5. From the Choose events dropdown list, select webhook.response.
  6. Click the + where button.
  7. From the Choose parameters dropdown list, select name.
  8. From the Choose operator dropdown list, select Equal.
    Result: A text field appears.
  9. In the text field, enter the value of the Action name from the Outgoing webhook node (for example, get email Hash).
    Tip: If you encoded a phone number, enter get phone Hash.
  10. Confirm by clicking Apply.
The Client Event Filter configuration
The configuration of the Client Event Filter

4. Send Custom Audience to Facebook

  1. On the Client Event Filter node, click the plus icon.

  2. From the dropdown list, select Outgoing webhook.
    Result: The Outgoing webhook appears on the dashboard, after the Client Event Filter.

  3. Double-click the node.

  4. On the pop-up, select the Custom webhook tab.

  5. In the action name, enter the name of an event that will appear on the customer’s profile event list, when the action defined in the webhook is executed (for example, custom audience).

  6. Leave the method at default (POST).

  7. In the URL field, enter the endpoint that contains the ID of Custom Audience you created in the Create an empty Custom Audience step (you can find the endpoint in the Facebook documentation).

  8. Set the content-type header to application/json (default).

  9. In the request body, enter the payload that contains the Jinjava code that refers to the response from the previous Outgoing webhook:

        {
     "payload": { 
     "schema": [ 
         "EMAIL" 
     ], 
     "data": [ 
         [ 
         "{{ event.params.body }}" 
         ]
       ] 
      }
     }
     
    If you encoded the phone number instead of an email address, use this payload:
        {
     "payload": { 
     "schema": [ 
         "PHONE" 
     ], 
     "data": [ 
         [ 
         "{{ event.params.body }}" 
         ]
       ] 
      }
     }
     
  10. Leave the Authorization section at default.

  11. Confirm by clicking Apply.

    The Outgoing webhook node configuration
    The configuration of the webhook node that sends customers to Custom Audience in Facebook
  12. On the Outgoing webhook node, click the plus icon.

  13. From the dropdown list, select End.

  14. In the upper right corner, click Save & Run.
    Result: On the customers’ profiles in CRM, you can see the webhook.response events with 200 status and "num_received": 1 in the response bodies. Then, go Facebook, to Facebook Manager > Audiences to check your Custom Audience.

Repeatable automation 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. Create a webhook that encodes email into SHA256

  1. On the Audience node, click the plus icon.
  2. From the dropdown list, select Outgoing webhook.
    Result: The Ougoing webhook appears on the dashboard after the Audience node.
  3. Double-click the Outgoing webhook node.
    Result: A pop-up appears.
  4. On the pop-up, select the Custom webhook tab.
  5. In the action name, enter the name of an event will appear on the customer’s profile event list when the action defined in the webhook is executed (for example, get email Hash).
    Tip: If you encode a phone number, replace get email Hash with get phone Hash.
  6. Leave the method at default (POST).
  7. In the URL field, enter the endpoint you requested from the Synerise Support team.
  8. Set the content-type header to application/json (default).
  9. In the request body, enter "name": "{{ client.email }}".
    Tip: To encode a phone number, replace {{ client.email }} with {{ client.phone }}.
  10. Leave the Authorization section at default.
  11. Confirm by clicking Apply.
The Outgoing webhook node configuration
The configuration of the webhook node that encodes an email hash

3. Wait for the email hash to be generated

This node checks if the emails are encoded into SHA256.

  1. On the Outgoing webhook node, click the plus icon.
  2. From the dropdown list, select Client Event Filter.
    Result: The Client Event Filter appears on the dashboard, after the Outgoing webhook node.
  3. Double-click the node.
    Result: A pop-up opens.
  4. Leave the Check option at default.
  5. From the Choose events dropdown list, select webhook.response.
  6. Click the + where button.
  7. From the Choose parameters dropdown list, select name.
  8. From the Choose operator dropdown list, select Equal.
    Result: A text field appears.
  9. In the text field, enter the value of the Action name that you entered Outgoing webhook node (if you copied from the procedure, it’s get email Hash).
  10. Confirm by clicking Apply.
The Client Event Filter configuration
The configuration of the Client Event Filter

4. Send Custom Audience to Facebook

  1. On the Client Event Filter node, click the plus icon.

  2. From the dropdown list, select Outgoing webhook.
    Result: The Outgoing webhook appears on the dashboard, after the Client Event Filter.

  3. Double-click the Outgoing webhook node.

  4. On the pop-up, select the Custom webhook tab.

  5. In the action name, enter the name of an event that will appear on the customer’s profile event list, when the action defined in the webhook is executed (for example, custom audience).

  6. Leave the method at default (POST).

  7. In the URL field, enter the endpoint that contains the ID of Custom Audience you created in the Create an empty Custom Audience step (you can find the endpoint in the Facebook documentation).

  8. Set the content-type header to application/json (default).

  9. In the request body, enter the payload that contains the Jinjava code that refers to the response from the previous Outgoing webhook:

        {
     "payload": { 
     "schema": [ 
         "EMAIL" 
     ], 
     "data": [ 
         [ 
         "{{ event.params.body }}" 
         ]
       ] 
      }
     }
     
    If you encoded the phone number instead of an email address, use this payload:
        {
     "payload": { 
     "schema": [ 
         "PHONE" 
     ], 
     "data": [ 
         [ 
         "{{ event.params.body }}" 
         ]
       ] 
      }
     }
     
  10. Leave the Authorization section to default.

  11. Confirm by clicking Apply.

    The Outgoing webhook node configuration
    The configuration of the webhook node that sends customers to Custom Audience in Facebook
  12. On the Outgoing webhook node, click the plus icon.

  13. From the dropdown list, select End.

  14. In the upper right corner, click Save & Run.
    Result: On the customers’ profiles in CRM, you can see the webhook.response events with 200 status and "num_received": 1 in the response bodies. Then, go to Facebook Manager > Audiences to check your Custom Audience.

Repeatable automation using either encoded email or phone

The repeatable automation that works based either on encoded email or phone number
The repeatable automation that works based either on encoded email or phone number

1. Choose customers

  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 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, click the Boolean icon icon.
  9. From the list, select Is true.
    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 webhook.
    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, click the Boolean icon icon.
  9. From the list, select Is true.
    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 webhook.
    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. Create webhooks that encode email address and phone number

  1. Double-click the Outgoing webhook connected to the has email Client Filter.
    Result: A pop-up appears.
  2. On the pop-up, select the Custom webhook tab.
  3. In the action name, enter the name of an event that will appear on the customer’s profile event list, when the action defined in the webhook is executed (for example, get email Hash).
  4. Leave the method at default (POST).
  5. In the URL field, enter the endpoint you requested from the Synerise Support team.
  6. Set the content-type header to application/json (default).
  7. In the request body, enter "name": "{{ client.email }}".
  8. Leave the Authorization section at default.
  9. Confirm by clicking Apply.
  10. Double-click the Outgoing webhook connected to the has phone Client Filter.
  11. Repeat steps from 2 to 9 with the following modifications:
    1. In step 3, replace get email Hash with get phone Hash.
    2. In step 7, replace "name": "{{ client.email }}" with "name": "{{ client.phone }}"
The Outgoing webhook node configuration
The configuration of the webhook node that encodes an email hash

4. Wait for the email address or phone hash to be generated

This node checks if the emails or phone numbers are encoded into SHA256.

  1. On the get email hash Outgoing webhook node, click the plus icon.
  2. From the dropdown list, select Client Event Filter.
    Result: The Client Event Filter appears on the dashboard, after the Outgoing webhook node.
  3. Double-click the node.
    Result: A pop-up opens.
  4. Leave the Check option at default.
  5. From the Choose events dropdown list, select webhook.response.
  6. Click the + where button.
  7. From the Choose parameters dropdown list, select name.
  8. From the Choose operator dropdown list, select Equal.
    Result: A text field appears.
  9. In the text field, enter the value of the Action name from the Outgoing webhook node (for example, get email Hash).
  10. Confirm by clicking Apply.
  11. On the get phone hash Outgoing webhook node, click the plus icon.
  12. Repeat steps from 2 to 10 for the waiting for phone Client Event Filter node.
    • In step 9, replace get email Hash with get phone Hash.
The Client Event Filter configuration
The configuration of the Client Event Filter

5. Send Custom Audience to Facebook

  1. On the waiting for email hash Client Event Filter node, click the plus icon.

  2. From the dropdown list, select Outgoing webhook.
    Result: The Outgoing webhook appears on the dashboard, after the Client Event Filter.

  3. Double-click the node.

  4. On the pop-up, select the Custom webhook tab.

  5. In the action name, enter the name of an event that will appear on the customer’s profile event list, when the action defined in the webhook will be executed (for example, custom audience).

  6. Leave the method at default (POST).

  7. In the URL field, enter the endpoint that contains the ID of the Custom Audience you created in the Create an empty Custom Audience step (find the endpoint in the Facebook documentation).

  8. Set the content-type header to application/json (default).

  9. In the request body, enter the payload that contains the Jinjava code that refers to the response from the previous Outgoing webhook:

        {
     "payload": { 
     "schema": [ 
         "EMAIL" 
     ], 
     "data": [ 
         [ 
         "{{ event.params.body }}" 
         ]
       ] 
      }
     }
     
  10. Leave the Authorization section to default.

  11. Confirm by clicking Apply.

  12. Double-click the waiting for phone hash Client Event Filter node.

  13. Repeat steps from 2 to 11.

    • In step 9, paste the code below:
        {
    "payload": { 
    "schema": [ 
        "PHONE" 
    ], 
    "data": [ 
        [ 
        "{{ event.params.body }}" 
        ]
      ] 
     }
    }
    
  14. At the end of each Outgoing webhook, add the End nodes.

  15. To activate the automation, click Save & Run.
    Result: On the customers’ profiles in CRM, you can see the webhook.response events with 200 status and "num_received": 1 in the response bodies. Then, go to Facebook Manager > Audiences to check your Custom Audience.

😕

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.