Get notified with webhooks | Fluid Attacks Help

Get notified with webhooks

Info on compatibility
Fluid Attacks' webhooks are not compatible with Google Chat and Slack.
The Fluid Attacks platform allows creating custom HTTP callbacks that are defined by User Managers through a URL (endpoint). These callbacks are triggered by events that occur in the group. When an event is triggered, an HTTP request is sent to the URL configured in the platform's Integrations section, notifying that the event has occurred. It is important to note that only the notifications informing of the selected events are sent.

To start setting up webhooks for a group or learn about existing ones, go to your organization's Integrations section, locate Webhooks under Others, and click on the gear icon.
Locate webhooks option on the Fluid Attacks platform
Advice on Webhooks card
Notice that the Webhooks card displays how many of the groups you have access to have this integration configured.
In the pop-up window, you can see the groups you have access to. If one or more webhooks have already been defined for a group, you see the Edit button. Otherwise, you see the Connect button. Either button opens a pop-up window with a table, which is explained below on this page.

Manage webhooks integration on the Fluid Attacks platform

Understand the Add hooks table

The table in the Add hooks pop-up window displays the endpoints you have configured to receive notifications for events you are interested in. Each column is explained below.

Open the Add hooks table on the Fluid Attacks platform

  • Name: Name to refer to the webhook
  • Url: The designated endpoint to which notifications are transmitted upon the occurrence of a specified event action
  • Token header: The header containing your token for the URL
  • Events: The list of events of which notifications are sent when they occur in the group

Events available for webhooks

Events refer to the actions of the platform of which you can receive notifications when they occur in your specific group. The following are the events for which you can set up webhooks:

  • AGENT_TOKEN_EXPIRATION: The DevSecOps agent token is about to expire.
  • ENVIRONMENT_REMOVED: An environment is removed from the Scope section
  • EVENT_CREATED: An event is created in the group
  • ROOT_CREATED: A new root is added in the Scope section
  • ROOT_DISABLED: A root is deactivated
  • VULNERABILITY_ASSIGNED: A vulnerability is assigned to a member of the group
  • VULNERABILITY_CREATED: A vulnerability is reported to the group
  • VULNERABILITY_DELETED: A vulnerability is deleted due to the realization of a reporting error, or because it was a duplicate or identified as a false positive
  • VULNERABILITY_SEVERITY_CHANGED: The severity score is changed
  • VULNERABILITY_VERIFIED: A request is sent to see the status of the reattack

Information sent of each event

When an event is triggered, an HTTP request is sent to the specified URL with the following body structure:

{
"group": "group_name",
"event": "event",
"info": {}
}

These are the definitions of what is sent:
  1. group: The group in which the event occurred
  2. event: The specific event that triggered the webhook
  3. info: An object containing additional details about the event (the structure of the info object varies depending on the event type)
The following table shows the details of the info object for different events:

Event
info object
AGENT_TOKEN_EXPIRATION
{
  "group_data": {
    "org_name",
    "exp_date",
  }
}
ENVIRONMENT_REMOVED
{
  "url_id",
  "root_id",
}
EVENT_CREATED
{
  "event_id",
}
ROOT_CREATED
{
  "type",
  "root_id",
}
ROOT_DISABLED
{
  "root_id",
}
VULNERABILITY_ASSIGNED
{
  "vulnerabilities",
  "finding_id",
  "responsible",
}
VULNERABILITY_CREATED
{
  "finding_id",
  "finding_title",
  "group_name",
  "severity_score",
  "severity_score_v4",
  "vulnerability_id",
  "vulnerability_specific",
  "vulnerabilit_where",
}
VULNERABILITY_DELETED
{
  "finding_id",
}
VULNERABILITY_SEVERITY_CHANGED
{
  "finding_id",
  "vulns_id",
}
VULNERABILITY_VERIFIED
{}

Manage your webhooks

Role requirement infoRole required: User Manager
There are three functions available for managing webhooks in Fluid Attacks' platform:

Add a webhook

To add a webhook, follow the steps below:

  1. Access your organization's Integrations section, click on the gear in the Webhooks card and then on the option next to the group for which you wish to set up the webhook. 

  2. Click on the Add hook button.

    Add webhook for a group on the Fluid Attacks platform

  3.  Fill out the Add hook information pop-up window. The fields are explained below the screenshot.

    Configure a webhook on the Fluid Attacks platform

    • Url: The URL of the endpoint of the hook where you want to receive event notifications.
    • Name: The name or alias of the webhook.
    • Token header: The header containing the token for that URL (this field is optional and defaults to the x-API-token value)
    • Token: The security token needed to access the URL
    • Events: Actions specific to the group for which you wish to receive notifications (select at least one; see the definitions of events available for webhooks above)
  4. Once all the fields are filled out, click on Confirm. It is advisable to validate that the endpoint is accessible by making a request.

Edit a webhook

To modify the information of a specific webhook already created for a group, follow these steps:

  1. Access your organization's Integrations section, click on the gear in the Webhooks card and then on the option next to the group for which you wish to modify a webhook. 

  2. Select the webhook and then click the Edit button.

    Select a webhook to edit on the Fluid Attacks platform

  3. In the new pop-up window, modify the configuration of the webhook as needed. (Read the descriptions of these fields from the instructions to add a webhook.) 

    Change a webhook configuration on the Fluid Attacks platform

  4. After making changes, click Confirm to save them. It is advisable to validate that the endpoint is accessible by making a request.

Remove a webhook

To remove a webhook that is no longer of interest to you, follow these steps:

  1. Access your organization's Integrations section, click on the gear in the Webhooks card and then on the option next to the group for which you wish to delete a webhook. 

  2. Choose the webhook and then click on the Remove button.

    Remove webhook on the Fluid Attacks platform

  3. A confirmation window pops up asking you to confirm that you want to delete the webhook. Upon clicking Confirm, the webhook is removed from the table.

    Confirm webhook deletion on the Fluid Attacks platform

Error messages

When you add or edit a webhook on Fluid Attacks' platform, the webhook is subjected to specific validations. You have to keep these validations in mind when performing those actions. If your webhook does not pass one or more checks, you get the corresponding error message(s). The following are the error messages you may get: 

  • Invalid data: The URL and/or the token are not valid.
  • Duplicated: You attempted to add a URL that already exists.
  • Unreached Host: The host URL was not found.
  • Not Found: The hook has not been found, or you do not have permission to access it.
Free trial message
Free trial
Search for vulnerabilities in your apps for free with Fluid Attacks' automated security testing! Start your 21-day free trial and discover the benefits of the Continuous Hacking Essential plan. If you prefer the Advanced plan, which includes the expertise of Fluid Attacks' hacking team, fill out this contact form.