Webhooks

Webhooks in DataGuard CPM allow your systems to listen for real-time updates to Citizen Permissions and Preferences. By setting up webhooks, you can ensure that your systems are always in sync with the latest consent data, enabling more responsive and accurate data handling.

Setting Up Webhooks

To create a new webhook, follow these steps:

1. Access the CPM UI: Log in to the DataGuard CPM UI.
2. Navigate to Integrations: Under the Integrations section, find the option to create a new webhook.
3. Configure the Webhook: Provide the URL that the webhook should POST to when triggered. You can choose from multiple authentication types to secure your webhook.

Webhook Request and Retry System

• POST Requests: The webhook system sends a POST request to the supplied URL whenever there is an update.
• Retry Mechanism: If a request fails, the system will retry up to 3 times. If it still fails, the system will wait an hour before trying again. This process ensures that no updates are lost, as all updates will be continually retried until they are successfully delivered.
• Pausing Webhooks: You have the option to pause a webhook. However, please note that while a webhook is paused, updates will not be queued, and any changes made during this time will be lost.

Types of Webhooks

DataGuard CPM offers three types of webhooks to suit different needs:

1. Effective Permissions Webhook

• Purpose: Sends the full state of a Citizen whenever there is a change. This includes not only the new changes but also all permissions and preferences that were unaffected by the change.
• Use Case: Ideal for systems that need a complete view of a Citizen’s current consent and preference state after every update.

2. Consent Receipts Webhook

• Purpose: Sends only the permissions and preferences that have changed. Unchanged fields are omitted from the payload.
• Use Case: Useful for systems that only need to track what has specifically been altered, reducing the amount of data processed.

3. Citizen Emails Webhook

• Purpose: Triggers when a Citizen email is ready to be sent, such as for a double opt-in email. This webhook provides all the necessary content, allowing you to forward it directly to your email system.
• Use Case: Simplifies the process of sending transactional emails related to consent, as DataGuard handles the content generation.

Authentication Options

DataGuard CPM supports two types of authentication for securing your webhooks:

API Key Authentication

• Authentication: You can specify whether the API key should be included in a header or query string. Additionally, you can define both the name of the field and the key itself.
• Use Case: Suitable for straightforward, key-based authentication methods where the API key needs to be included in the webhook request.

OAuth 2.0 Authentication

• Authentication: DataGuard CPM supports OAuth 2.0 by providing the option to include a token in the Authorization header with the Bearer prefix.
• Use Case: Ideal for environments where OAuth 2.0 authentication is required. To ensure the token is always valid, we recommend you set up a schedule to update the token before expiry using the Update a Subscription by ID endpoint.

Summary

Webhooks in DataGuard CPM provide a powerful way to keep your systems updated with the latest Citizen consent and preference changes. With support for different types of webhooks and robust retry mechanisms, you can ensure that no updates are missed. The flexibility in authentication options further allows you to secure your integrations according to your specific needs.

Payload Examples

Effective Permissions

{
  "applicationId": "your-app-id",
  "citizenId": "DataGuard-id",
  "externalRef": "your-customer-ref",
  "permissions": [
    {
      "transactionId": "permission-transaction-id",
      "optionType": "option/group",
      "optionId": "option-id",
      "justification": "lawful-basis",
      "state": "STATE",
      "channel": "channel-txn-received-via",
      "campaign": "attributed-campaign-id",
      "privacyPolicyId": "privacy-policy-id-in-DataGuard",
      "privacyPolicyRef": "reference-of-above",
      "permissionStatementId": "permission-statement-id-in-DataGuard",
      "permissionStatementRef": "reference-of-above",
      "recordedBy": "id-of-who-recorded-txn",
      "recordedByName": "name-of-above",
      "recordedClient": "system/client-id",
      "recordedClientName": "system/client-name",
      "delegatedAuthorityId": "id-of-delegate-who-recorded-txn",
      "delegatedAuthorityName": "name-of-delegate-who-recorded-txn",
      "recordedAt": "iso-timestamp",
      "obtainedAt": "iso-timestamp",
      "validFrom": "iso-timestamp",
      "validUntil": "iso-timestamp"
    }
  ],
  "preferences": [
    {
      "preference": "ref-of-preference",
      "choices": [
        {
          "reference": "ref-of-choice-made",
          "label": "human-readable-label-of-choice"
        }
      ],
      "label": "display-label-of-preference",
      "submissionId": "preference-submission-id",
      "updatedAt": "iso-timestamp"
    }
  ],
    "sentAt": "iso-timestamp"
}