Webhooks is a straightforward and simple way to integrate Signatu with any other IT system. Perhaps you want your CRM system to be notified about any changes to your user's consent status, or you want your ad-ops team to be notified about new trackers running on your website through their Slack channel.

Signatu makes this easy with out-of-the-box support for Webhooks. In this blog post we describe the overall format, the specifics for the Signatu Consent and Trackerdetect services, and close with a step-by-step example on how to get notifications into your Slack channel.

Event format

All posted events have the following envelope:

{
  type: "event_type", 
  text: "Some description in English", 
  data: {
    /** Event-specific data */
  }
}

Each event type will have a different data payload. As of February 2018 we support event types consent and trackerdetect, as described below.

There are cases where you need to notify external systems such as your CRM system(s) about the user consent action. The consent service supports posting the complete consent event when it happens.

Consent Event

The event type is consent and the data field will contain the complete consent event as described in the documentation. Here's an example:

{
  "type": "consent", 
  "text": "Subject SUBJECT_ID just gave consent to https://policy_url", 
  "data": {
    "id": "SUBJECT_ID",
    "scope": "4.3",
    "subject": "3",
    "issuer": "https://your_webpage/contact",
    "target": "https://policy_url",
    "source": "https://your_webpage",
    "action": true,
    "token": "35BA8F",
    "createdAt": "2018-02-25T19:21:46.000Z"
  }

Trackerdetect

Trackerdetect supports webhooks as an alternative or supplement to e-mail notifications. The notifications are filtered according to the Alerts settings in the Site configuration.

Trackerdetect event filter

Note that Trackerdetect will post separate events per tracker. So if a run discovers 5 new trackers, the webhook will receive 5 separate events.

Trackerdetect Event

Events of type trackerdetect has one type:

  • FOUND_NEW_TRACKER: The found tracker has not been seen for this site before.
  • FOUND_APPROVED_TRACKER: The found tracker has been actively approved by in the Site Specification.
  • FOUND_NOT_APPROVED_TRACKER: The found tracker has been actively NOT approved by in the Site Specification.
  • FOUND_UNKNOWN_TRACKER: The found tracker has been seen before, but no active action has been made to approve it.

The following is an example of the full event, including the envelope used for all events.

{
  type: "trackerdetect", 
  text: "FOUND_UNKNOWN_TRACKER: facebookconnect for analysis https://signatu.com/trackerdetect/result...", 
  data: {
    "type": "FOUND_UNKNOWN_TRACKER",
    "tracker": {
        "id": "facebookconnect",
        "scripts": [
            {
                "type": "script",
                "url": "http://connect.facebook.net/en_US/fbds.js", 
                "sha256": "9c0bee7faba8ce0b36ebd9aa1bc712240d4d4f2f22adb3e698ffb2e4df1f0141",
                "parentPageId": "6e2e05735b8c470f7ada4ff03c36ab9a2700abe6b8bef0c84c51643e0f99bfbf"
            }
        ],
        "pixels": [],
        "iframes": [],
        "seen": "2017-11-17T09:26:41.629Z",
        "data": {}
    }
  }
}

Slack example

Perhaps your team uses Slack for collaboration. You can easily configure Trackerdetect to post notifications to a Slack channel of your choosing. To do so, follow these steps:

  1. In your Slack account, go to Custom Integrations and choose Incoming WebHooks.
  2. Click Add Configuration
  3. Choose channel to post to and click Add Incoming WebHooks Integration.
    1.Copy the Webhook URL. It should look something like https://hooks.slack.com/services/SOME_TOKEN.

You can now register the Webhook URL in Signatu:

  1. Get hold of your API Key and Access Token from your account Credentials page.
  2. Register the Webhook using an HTTP client, e.g., curl, replacing url with the Webhook URL from above. In this example we register the consent event, but it looks identical for the trackerdetect event.
$ curl https://api.signatu.com/webhooks/v0 \
      -H 'Authentication: Bearer YOUR_ACCESS_TOKEN' \
      -H 'x-api-key: YOUR_API_KEY' \
      -H 'Content-Type: application/json' \
      -d  \
       '{\
          "url": "https://hooks.slack.com/services/SOME_TOKEN", \
          "events": ["consent"] \
       }'

Read more about using Webhooks in the Signatu documentation.