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 notifications feature is only available on the Team plan. You can manage your current plan on your account page.

Now that the project is being analyzed (automatically or manually) by SymfonyInsight, you may like to receive notifications about the results of these analyses. SymfonyInsight natively supports three messaging applications: Slack, Microsoft Teams 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 that will receive a POST request when the analysis status changes.

Note

The URL used for the WebHook is hosted in your own servers and needs to be publicly accessible.

Configure a custom WebHook on SymfonyInsight

Custom WebHooks configuration can be put either in the .symfony.insight.yaml 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 safer to configure it via the SymfonyInsight Web interface.

Note

You can learn more about how to configure SymfonyInsight 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 SymfonyInsight 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 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.symfony.com/projects/45afb680-d4e6-4e66-93ea-bcfa79eb8a87",
        "api_url": "https://insight.symfony.com/api/projects/45afb680-d4e6-4e66-93ea-bcfa79eb8a87"
    },
    "analysis": {
        "number": 10229,
        "name": "fabpot / symfony #10229",
        "url": "https://insight.symfony.com/projects/45afb680-d4e6-4e66-93ea-bcfa79eb8a87/analyses/10229",
        "api_url": "https://insight.symfony.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 includes some basic information of the project being analyzed (you can get more details about the project using the API).
  • analysis includes the most important information about the performed analysis (you can get more details about the analysis 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 textual description to the status, in a human readable format.