Configuring the Notification Service

In this guide we're going to see how you can be notified automatically when an analysis is completed.

If you're not familiar with GraphQL, please have a look at its dedicated section in this documentation.

In order to help you to use AdSecure with your infrastructure, we've developed a notification service that aims to keep you informed about the status of each analysis.

This service is going to notify you, for example, when an analysis is completed, when the AdSecure crawler has found a violation or an alert, etc...

Prerequisites

Before starting this guide, please be sure that you're ready to use our service by following the steps illustrated in the Quickstart section.

Simple case — HTTP callback

A notification could sent by using different medium to inform you about the analysis's status. For this simple example, Let's create a notification setting that's going to send us back an HTTP request each time the AdSecure crawler find a violation.

In a similar way we've created an Analysis in the First Analysis guide, we're going to create a new Notification entry by sending to the GraphQL API a mutation query.

When you want to create a Notification, the following parameters are required to be set in the input:

• The name which is going to help us to easily remember the scope of this notification. This value is also going to be used to generate the notification's login.
• The uri which is representing the endpoint where you would like to receive this notification. In this example, we're going to use the webhook.site service in order to simplify the flow, but feel free to use the endpoint of your choice.
• The trigger that you want to subscribe to. This key could take one of the following values:
  • ON_DONE: It will cause the notification to be sent when the analysis has its status updated as DONE.
  • ON_ERROR: It will cause the notification to be sent when the analysis has its status updated as ERROR.
  • ON_VIOLATION: It will cause the notification to be sent if at least one violation was found during the analysis.
  • ON_ALERT: It will cause the notification to be sent if at least one violation that is considered as an alert was found during the analysis.

Query

mutation {
  createNotification(input: {
    name: "Notify me on violation",
    uri: "https://webhook.site/6ca79585-db5d-43ba-9eee-c9206c6544f6",
    trigger: "ON_VIOLATION"
  }) {
    login
  }
}

Response

{
  "data": {
    "createNotification": {
      "login": "notify-me-on-violation"
    }
  }
}

We can now use this notification setting when we create a new analysis. We need for that to set the notification's login as an additional parameter to the example illustrated in the First Analysis's guide and we ask the API to return us an additional field notifications as feedback.

As you can see, you can add multiple notification settings to a single Analysis, if you like for example to be notified on multiple triggers and or different endpoints.

Query

mutation {
  createAnalysis(input: {
    url: "https://examples.adsecure.com/404",
    notifications: [
      "notify-me-on-violation"
    ]
  }) {
    id
    notifications {
      trigger
      uri
    }
  }
}

Response

{
  "data": {
    "createAnalysis": {
      "id": "YW5hbHlzaXN8YThiYzk0M2ItNTY3ZS00NzA5LWIwOWItMTI1YmMzNGMxMjUwfDIwMTgtMDktMDI=",
      "notifications": [
        {
          "trigger": "ON_VIOLATION",
          "uri": "https://webhook.site/6ca79585-db5d-43ba-9eee-c9206c6544f6"
        }
      ]
    }
  }
}

If you open the web page related to your notification's URI (i.e. adding the # character to the current URI) you'll be able to see the notification sent by our service:

https://webhook.site/#/6ca79585-db5d-43ba-9eee-c9206c6544f6

A notification is sent as a POST request with the following payload:

{
  "id": "YW5hbHlzaXN8YThiYzk0M2ItNTY3ZS00NzA5LWIwOWItMTI1YmMzNGMxMjUwfDIwMTgtMDktMDI=",
  "object": "RECOGNITION",
  "trigger": "ON_VIOLATION",
  "report": "https://s3.amazonaws.com/adsecure/analysis/year=2018/month=9/day=4/YW5hbHlzaXN8YThiYzk0M2ItNTY3ZS00NzA5LWIwOWItMTI1YmMzNGMxMjUwfDIwMTgtMDktMDI=.json",
}

If we take each element of this payload one by one we have:

• id which represents the Analysis's id that is related to this notification.
• report which provide you the detailed version of an analysis.
• trigger which represent your subscription.

That's all for this guide, feel free to use this notification service as you like!