Webhooks

Capture real time updates using our subscription webhooks

Get Started

Use the subscriptions service (API is here) to set the URL to push updates to. This service can be secured using Oauth2-pattern refresh tokens, a static token, or left unsecured depending on your preference.

These messages are attempted up to 3 times initially depending on an http error response being received. If 3 successive attempts of the same message fail the payload is persisted in a failures database to be periodically retried every hour.

UML sequence for subscriptions following an Oauth2 flow shown below:

The message payload is shown below:

webhook message payload

{
  "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"
}

🚧

Use sentAt timestamp

The DataGuard subscription webhook will provided a sentAt ISO8601 timestamp in the message payload. This can be used in the logic for updating your synced system records. NOTE - the messages will contain the full set of permissions and preferences on each update (not just the changed values).