Server Webhook integration

When a new data subject request is made, Transcend can send a WebhookWebhook - A webhook is an event notification in the form of an HTTP POST request from one server (the emitter) to another (the listener). It contains a request body with information about the event. The receiving server (the listener) can respond to the POST request with a response body (this is often referred to as a callback). to one of your servers. Your server can implement some business logic required to fulfill the request and then asynchronously notify Transcend once that request has been fulfilled.

👍

Check out our examples

We have examples on GitHub. The javascript example is deployed live at our demo privacy center.

What's involved

There are four steps to integrating your server with Transcend:

1. Create the data silo on Transcend
Using the Transcend Admin Dashboard, create a new data silo and input the webhook URL that should be notified.

2. Receive a webhook
Transcend will send a notification to your server for each new Data Subject RequestData Subject Request - (DSR) This is a request by the data subject to access, erase, port, or rectify their personal data. It also includes objections to the processing of personal data and requests to restrict the processing of personal data..

3. Look up and operate on user data
Your server will need to find the user specified by the WebhookWebhook - A webhook is an event notification in the form of an HTTP POST request from one server (the emitter) to another (the listener). It contains a request body with information about the event. The receiving server (the listener) can respond to the POST request with a response body (this is often referred to as a callback). and perform an operation such as retrieving or deleting their personal data.

4. Notify the Transcend API of completion
Use our API to notify Transcend when the server has completed processing. For an access request, this means uploading data. For an erasure or opt out request, this means notifying Transcend that the job has been completed.

1. Create the data silo on Transcend

  1. Go to your Data Map to connect the "Server Webhook" integration type.
  2. Give your silo a title (e.g. "Core Backend Application")
  3. Set the webhook URL that we should notify
  4. Click Connect to create the data silo and store the newly created API key
  5. Click "View in Data Map" and drop down the "Manage Datapoints" tab to configure what types of requests your server should be notified about.

2. Receive a webhook

Transcend will send a POST request to the URL from step 1. The route should first validate that the webhook is in fact coming from your sombra gateway by validating the incoming x-sombra-token header. Please refer to this guide for information on verifying the webhook signature.

Request headers:

{
  "x-transcend-nonce": "<A_VALUE_TO_RETURN>",
  "x-sombra-token": "<A_JSON_WEB_TOKEN_TO_VERIFY>",
  "accept": "application/json",
  "content-type": "application/json",
  "via": "HTTPS/1.1 <<yourOrganizationName>>.sombra.transcend.io:5041 (Sombra)"
}

Request body:

{
  "type": "ACCESS", // Could be ERASURE, ...
  "coreIdentifier": {
    "value": "some.user.id" // The globally unique user ID for the user
  },
  "extraIdentifiers": {
    "email": [{
      "id": "55014253-0af6-47c4-baa8-5f383c0210ff",
      "value": "[email protected]"
    }],
    "custom": []
  },
  "dataSubject": {
    "type": "customer"
  },
  "isTest": false,
  "extras": {
    "request": {
      "details": "",
      "id": "2cde58cd-5405-434e-8c6a-dd71a726d5b3",
      "link": "https://app.transcend.io/request/2cde58cd-5405-434e-8c6a-dd71a726d5b3/8c4f2cdf-c2bf-4a4c-9fe4-0048d69073d4",
      "verifiedAt": "2019-04-26T17:55:22.773Z",
      "createdAt": "2019-04-26T17:55:21.723Z",
      "locale": "en",
      "origin": "PRIVACY_CENTER"
    },
    "organization": {
      "id": "aaba371a-1ca0-4c55-9231-a1d8088a0e7d",
      "name": "<<yourOrganizationName>>",
      "uri": "<<yourOrganizationName>>"
    },
    "profile": {
        "createdAt": "2020-09-29T08:33:46.080Z",
        "id": "3ec04023-b70b-425d-9af1-fec1d7006267",
        "updatedAt": "2020-09-29T08:33:46.080Z",
        "RequestDataSiloId": "6c10925e-53fc-46c1-bfb7-90ff420cfc2e",
        "identifier": "some.user.id", // could be same as coreIdentifier.value or profile.value, this is what should be responded to as "profileId"
        "type": "email" 
    },
    "dataSilo": {
      "id": "8c4f2cdf-c2bf-4a4c-9fe4-0048d69077d4",
      "title": "Internal Database",
      "description": "Send a webhook to a server and post back through our API",
      "link": "https://app.transcend.io/data-map/silo/8c4d2cff-c4bf-4a4c-9fe4-0048d69077d4"
    }
  }
}

Upon receiving the webhook, you should validate that the incoming event type is able to be processed by your server, enqueue the job to be processed and then respond back to the webhook with:

  • a status code 200 OK if the request is queued up properly
  • status code 401 if the event type is unknown or the signature failed to validate
  • status code 204 if no user was found to be processed. You may also respond with status code 200 and report later that no users were found when Responding to DSRs.

3. Look up and operate on user data

Using the webhook fields type, coreIdentifier.value, extras.profile.identifier and extras.profile.type to implement the event type on your server. This part of the process is going to be a unique to your business. This may involve:

  • returning or removing rows from a database
  • returning or removing file from a filesystem
  • replacing fields containing personal data with anonymized placeholders

Please consult with your Transcend account representative on recommendations or guidelines for this process.

4. Notify the Transcend API of completion

Once your server has successfully completed the processing of the request, you must send a POST request to Transcend that indicates that processing has been completed. In the case of a Data Subject Access Request, this will also include uploading any data associated with the end user.

Please refer to this guide for information on responding to DSRs.