Integrating with Webhooks

You can use webhooks to notify the occurrence of an event in real-time. Instead of frequently polling a system to keep up to date with events, the system can call an HTTP URL with data pertaining to an event as they occur.

OneTrust can consume events that are called out by many modern applications. Sample events include the following:

  • A new lead created in Marketo

  • Prospect updates their profile information in Salesforce

  • Newly created asset in ServiceNow

  • Consumer unsubscribes from marketing emails

The following tasks are required for event consumption by OneTrust to occur:

  • Defining an event on an external system. This is when OneTrust should be called.

  • Information pertaining to the event the system will provide to OneTrust.

  • An endpoint (URL) that the external system will call to when this event occurs.

  • An authentication method with OneTrust. This verifies that the system is in fact calling the endpoint.

To create a webhook trigger in OneTrust

Note:

The following integration uses sample JSON from sent through Postman to trigger a workflow, parse the body, and then include the parameters in the body to a make a second call to Webhook.site, the example system for this documentation.

  1. On the Integrations menu, select Connections.

    The Connections screen appears.

  2. Click the Add New button.

    The Create Workflow modal appears.

  3. Enter a name, description, and the associated system for the new workflow.
  4. Click the Create button.

    The Workflow Builder screen appears.

  5. In the Add OneTrust Trigger block, go to the Built-in tab.
  6. Select Webhook.

    The Webhook Action block appears.

  7. Complete the fields.


    Field
    Description
    HTTP POST URL

    Copy this URL to use later as the request URL in your external system.

    Payload Type

    Select JSON as your Payload Type.

    Sample

    Paste the sample JSONin the Sample field.

    JSON 
    {
    "firstname": "John",
    "lastname": "Doe",
    "email": "jdoe@onetrust.com"
}
  8. Click the Done button.

To obtain a webhook URL

  1. Go to Webhook.site and copy the provided URL.


  2. Return to the OneTrust application, then click the Add button to add a new block.
  3. In the System tab, select POST http POST request.

    The Generic: POST http POST request block appears.

  4. Select None in the Select Credential field, then click the Next button.
  5. Complete the fields, then click the Finish to save and activate the workflow. For more information, see Generic POST Request Screen Reference.

Generic POST Request Screen Reference



Field
Description
Request URL

Paste the webhook.site URL you copied from webhook.site into the Request URL field.

Body

Enter a JSON dynamic lookup option. It should resemble the following example:

JSON 
{  
   "firstNameFlow":"${(event.payload.firstname)!}",
   "emailFlow":"${(event.payload.email)!}"
}

To verify the webhook integration

You can call the workflow from an external system to test the webhook. These instructions use Postman as a proxy system to demonstrate this verification.

  1. Copy the URL from the Webhook Action trigger block in the OneTrust application.
  2. In Postman, create a new POST request.
  3. Paste the trigger URL in the Enter request URL field.
  4. In the Headers tab, enter your desired authentication method.
    Client Credentials

    a secure authentication method as the access token can be set to expire, versus API keys which are valid until revoked. The Client ID and Client Secret are initially provided to get the token. All calls thereafter will not contain the ID or secret, reducing the changes of compromised credentials.

    As seen in Postman, you will need to select OAuth 2.0 in the Authorization tab and then generate the new access token. Ensure the authorization data is added to the Request Headers.





    API Keys

    a standard authentication method to provide long-term access though less secure than OAuth authentication.

    As seen in Postman, you will need to provide the API key and value in the Headers tab.



  5. Go to the Body tab and enable raw.
  6. Enter the JSON dynamic lookup option in the open body.
  7. Click the Send button.
  8. If configured correctly, you will receive a requestId back in the Response body with a 200/202 status code.


  9. Return to the webhook.site to verify that the API call came in.


Webhook Payload Types

Below are the payload types that are available in the Response tab of OneTrust actions for webhook configuration.

Note:

Keys that contain a null value will be removed from the payload for optimization.

  • JSON

  • Form-URL-Encoded

  • XML

  • Attachment

    Note:

    This payload type has a number of extension types to select from. The action will default to ADAPTIVE.



Content-types for Webook Payloads

The following table details which content-types are available for each payload type supported by OneTrust. Content-types are needed when providing key-value pairs in the headers of your API call to a webhook.



Webhook Payload

Content-Type Example

JSON

application/json

Form URL Encoded

application/x-www-form-urlencoded

XML

application/xml

Adaptive/Attachments

application/<file-extension>

For PDF, this would be application/pdf