Documentation

Doc index page

Configure a custom WebHook

Note

This document considers that the project is ready and that you successfully ran a first analysis on the code. If this is not the case yet, read the "Getting started" section.

Note

The notification features is only available on Business plans (Pro, Enterprise, and Premium). You can manage your current plan on your account page.

Now that the project is being analyzed (automatically or manually) by SensioLabsInsight, you may like to receive notifications about the results of these analysis. SensioLabsInsight natively supports two messaging applications: Slack and HipChat.

However, in some cases you may need to handle the analysis status differently. For these scenarios, you can use custom WebHooks. A custom WebHook is a URL we will send a POST request to when the analysis status changes.

Note

The URL used for the WebHook needs to be publicly accessible.

Configure a custom WebHook on SensioLabsInsight

Custom WebHooks configuration can be put either in the .sensiolabs.yml file or on the project edition page. While we usually recommend to put configuration in the file, notifications configuration can be sensitive as anyone having access to the WebHook URL can trigger it. It is therefore more secure to put it in the SensioLabsInsight Web interface.

Note

You can learn more about how to configure SensioLabsInsight on the dedicated documentation page.

Click on the "Edit project" link on the project page and add the following lines in the "Advanced configuration" section:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
notifications:
    - type: webhook

      # Your custom WebHook URL
      url: https://example.com/my-webhook-url

      # On which event SensioLabsInsight should post notifications
      on_pending: true  # Notify when an analysis is marked as pending
      on_success: true  # Notify when an analysis succeeded
      on_failure: true  # Notify when an analysis failed or errored

Once configured, you you will receive JSON payloads via POST on the specified URL. These requests will look like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
POST /my-webhook-url HTTP/1.1

{
    "project": {
        "id": "45afb680-d4e6-4e66-93ea-bcfa79eb8a87",
        "name": "symfony",
        "url": "https://insight.sensiolabs.com/projects/45afb680-d4e6-4e66-93ea-bcfa79eb8a87",
        "api_url": "https://insight.sensiolabs.com/api/projects/45afb680-d4e6-4e66-93ea-bcfa79eb8a87"
    },
    "analysis": {
        "number": 10229,
        "name": "fabpot / symfony #10229",
        "url": "https://insight.sensiolabs.com/projects/45afb680-d4e6-4e66-93ea-bcfa79eb8a87/analyses/10229",
        "api_url": "https://insight.sensiolabs.com/api/projects/45afb680-d4e6-4e66-93ea-bcfa79eb8a87/analyses/10229",
        "grade": bronze,
        "remediation_cost": 214.75
    },
    "status": "success",
    "status_text": "Code quality OK."
}

The payload is structured around four keys:

  • project is the project containing the analysis (you can get more details about it using the API).
  • analysis is the representation of the analysis (you can get more details about it using the API).
  • status is the status of the analysis, it can be one of pending, success, failure, analysis_error, or config_error.
  • status_text is the text corresponding to the status, in a human readable format.