---
title: "Webhook"
description: "Learn how to integrate StackHawk with custom Webhooks for automated API security testing and notification."
url: https://docs.stackhawk.com/integrations/workflows/webhook/
---

# Webhook

![webhook](https://docs.stackhawk.com/images/integrations/logos/webhooks.svg)

The Webhook integration sends HTTP POST requests to your API endpoints when StackHawk events occur. Use webhooks to connect StackHawk with internal tools, custom dashboards, or any service that accepts HTTP callbacks.

## Overview

Configure webhooks to receive notifications for any of these events:

### Scan Events

| Event | Description |
| - | - |
| Scan Started | Fires when a scan begins |
| Scan Completed | Fires when a scan finishes successfully, includes findings data |
| Scan Errored | Fires when a scan encounters an error |

### Audit Log Events

| Event | Description |
| - | - |
| User Activity | Fires on user actions within your organization, such as inviting users, adding API keys, modifying integrations, and more |
| Organization Activity | Fires on organization-level events such as triaged alerts sent to third parties |

Each webhook request includes a JSON payload with event details. You can configure custom authentication headers, filter by specific event types, and test webhooks before enabling them for production use.

## Requirements

- A StackHawk account
- A plan with the Webhook Integration enabled. Contact [StackHawk Support](https://docs.stackhawk.com/support/) to enable it.

## Setup

1. Log into StackHawk and navigate to the [Webhook Integration page](https://app.stackhawk.com/integrations/webhook/).

2. Click **Add Webhook**. In the panel that opens, configure:

   - **Name** and **Description**
   - **Scan Data For** — select target application(s) or “All Applications”
   - **Events** — select which events trigger the webhook (e.g. Scan Started, Scan Completed, Scan Errored, User Activity, Organization Activity)
   - **User Activity Types** — optionally filter which user activities to receive (leave empty for all)
   - **Organization Activity Types** — optionally filter which organization activities to receive (leave empty for all)
   - **Auth Header Name** and **Auth Header Value** — optional authentication headers
   - **Webhook Endpoint URL** — your HTTPS endpoint

3. Click **Save**. StackHawk sends a test payload and displays the response. Use **Test** to send additional test requests for debugging.

4. Toggle the webhook to **Enabled** to start receiving live events.

![Create Webhook Integration Screenshot](https://docs.stackhawk.com/images/integrations/webhook/create-webhook.png)

### Allowed IP Addresses

> **Warning:** If your Webhook Consumer has access restricted by IP address, please add the following IP addresses to the allowed list:

- `44.227.38.189`
- `54.69.98.33`
- `44.227.81.160`

## Webhook Management

Click the **…** menu on any webhook to access management options:

| Action | Description |
| - | - |
| Edit | Modify webhook settings, endpoint, or event triggers |
| Enable/Disable | Toggle whether the webhook receives live events |
| Delete | Remove the webhook permanently |

![Webhook Management Integration Screenshot](https://docs.stackhawk.com/images/integrations/webhook/display-webhook.png)

## Payload

Enabled webhooks receive a JSON payload via HTTP POST for each triggered event. If you configured authentication headers, they are included in the request.

### Scan Completed

The Scan Completed payload includes:

- [Scan](#scan) metadata (ID, application, environment, timestamps)
- [Findings](#finding) with vulnerability details and affected paths
- [CompletedScanStats](#completedscanstats) summary of findings by severity and triage status

**Example payload:**

```json
{
  "service": "StackHawk",
  "scanCompleted": {
    "scan": {
      "id": "21a4f2da-740b-40d9-9557-696d8aca6a76",
      "hawkscanVersion": "4.0.0",
      "env": "Development",
      "status": "COMPLETED",
      "application": "Contosso",
      "startedTimestamp": "2021-05-18T00:26:41.892Z",
      "scanURL": "https://app.stackhawk.com/scans/21a4f2da-740b-40d9-9557-696d8aca6a76",
      "tags": [
        {
          "name": "category",
          "value": "${CATEGORY_FROM_ENV:default}"
        }
      ]
    },
    "scanDuration": "1",
    "spiderDuration": "33",
    "completedScanStats": {
      "urlsCount": "5",
      "duration": "34",
      "scanResultsStats": {
        "totalCount": "3",
        "lowCount": "2",
        "mediumCount": "0",
        "highCount": "0",
        "lowTriagedCount": "0",
        "mediumTriagedCount": "1",
        "highTriagedCount": "0"
      }
    },
    "findings": [
      {
        "pluginId": "10106",
        "pluginName": "HTTP Only Site",
        "severity": "Medium",
        "host": "http://localhost:8080",
        "paths": [
          {
            "path": "/test",
            "method": "GET",
            "status": "FALSE_POSITIVE",
            "pathURL": "https://app.stackhawk.com/scans/21a4f2da-740b-40d9-9557-696d8aca6a76/finding/10106/path/61036/message/49"
          }
        ],
        "pathStats": [
          {
            "status": "FALSE_POSITIVE",
            "count": 1
          }
        ],
        "totalCount": "1",
        "category": "HTTP Data Stream Protection",
        "findingURL": "https://app.stackhawk.com/scans/21a4f2da-740b-40d9-9557-696d8aca6a76/finding/10106"
      },
      {
        "pluginId": "10021",
        "pluginName": "X-Content-Type-Options Header Missing",
        "severity": "Low",
        "host": "http://localhost:8080",
        "paths": [
          {
            "path": "",
            "method": "GET",
            "status": "NEW",
            "pathURL": "https://app.stackhawk.com/scans/21a4f2da-740b-40d9-9557-696d8aca6a76/finding/10021/path/32294/message/8"
          },
          {
            "path": "/",
            "method": "GET",
            "status": "NEW",
            "pathURL": "https://app.stackhawk.com/scans/21a4f2da-740b-40d9-9557-696d8aca6a76/finding/10021/path/31943/message/1"
          }
        ],
        "pathStats": [
          {
            "status": "NEW",
            "count": 2
          }
        ],
        "totalCount": "2",
        "category": "Information Leakage",
        "findingURL": "https://app.stackhawk.com/scans/21a4f2da-740b-40d9-9557-696d8aca6a76/finding/10021"
      }
    ]
  }
}
```

#### Scan

Metadata for a HawkScan run.

```jsonc
{
  "id": "21a4f2da-740b-40d9-9557-696d8aca6a76", // The scan id
  "hawkscanVersion": "4.0.0", // The version of HawkScan used for this scan
  "env": "Development", // The name of the scanned application
  "status": "COMPLETED", // one of either STARTED COMPLETED or ERROR
  "application": "Contosso", // scanned application
  "startedTimestamp": "2021-05-18T00:26:41.892Z", // ISO-8601 timestamp of when the scan was started
  "scanURL": "https://app.stackhawk.com/scans/21a4f2da-740b-40d9-9557-696d8aca6a76", // link to the StackHawk Platform for this specific scanned path
  "tags": [
    {
      "name": "category", // Tag names
      "value": "${CATEGORY_FROM_ENV:default}" // Tag value interpolated from environment
    }
  ]
}
```

#### CompletedScanStats

Summary of scan results including finding counts by severity and triage status.

```jsonc
{
  "urlsCount": 27, // Number of scanned urls
  "duration": 44, // Time in seconds for the scan to run
  "scanResultsStats": {
    "totalCount": 12, // Total number of findings
    "lowCount": 5, // Total number of low findings
    "mediumCount": 4, // Total number of medium findings
    "highCount": 3, // Total number of high findings
    "lowTriagedCount": 2, // Total number of low findings that have been triaged
    "mediumTriagedCount": 0, // Total number of medium findings that have been triaged
    "highTriagedCount": 1 // Total number of high findings that have been triaged
  }
}
```

#### Finding

An individual vulnerability detected during the scan. Each finding includes [Paths](#path) (specific endpoints affected) and [PathStats](#pathstats) (triage status counts).

```jsonc
{
  "pluginId": "40012", // The Id of the scanner extension that reported the finding
  "pluginName": "Cross Site Scripting (Reflected)", // Name of the plugin or vulnerability found
  "category": "Input Sanitization", // What vulnerability category this corresponds to
  "severity": "High", // High, Medium or Low criticality of the finding
  "host": "http://localhost:3333", // The web application host that was scanned
  "paths": [ ... ], // a list of all paths
  "pathStats": [ ... ], // a list of statistics for the found paths
  "totalCount": 4, // how many scanned paths correspond with this finding
  "findingURL": "https://app.stackhawk.com/scans/21a4f2da-740b-40d9-9557-696d8aca6a76/finding/40012" // link to the StackHawk Platform for this finding's overview.
}
```

#### PathStats

Count of paths grouped by triage status.

```jsonc
{
  "status": "NEW", // one of either NEW, FALSE_POSITIVE, RISK_ACCEPTED or PROMOTED
  "count": "1" // how many of the paths are triaged with that status
}
```

#### Path

A specific endpoint where the vulnerability was detected.

```jsonc
{
  "path": "/?option=javascript:alert(1);&search=ZAP&utf8=✓", // The specific path relative to the hostname
  "method": "POST", // HTTP method or GraphQL operation
  "status": "NEW", // one of either NEW, FALSE_POSITIVE, RISK_ACCEPTED or PROMOTED
  "pathUrl": "https://app.stackhawk.com/scans/21a4f2da-740b-40d9-9557-696d8aca6a76/finding/40012/path/595936/message/258" // link to the StackHawk Platform for this scanned path
}
```

### Audit Event

The Audit Event payload fires when user or organization activity occurs within your StackHawk organization. You can configure webhooks to receive all audit events or filter by specific activity types.

**Example payload:**

```json
{
  "service": "StackHawk",
  "auditEvent": {
    "eventId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "eventType": "USER_ACTIVITY",
    "eventAction": "API_KEY_ADDED",
    "organizationId": "12345678-abcd-1234-efgh-123456789012",
    "userId": "87654321-dcba-4321-hgfe-210987654321",
    "userName": "Jane Smith",
    "userEmail": "jane@example.com",
    "userIPAddr": "192.168.1.100",
    "payload": "{\"apiKeyName\":\"CI/CD Key\"}",
    "timestamp": "2025-03-15T14:30:00.000Z"
  }
}
```

#### AuditEventMessage

Details about the audit activity that triggered the webhook.

```jsonc
{
  "eventId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", // Unique identifier for this audit event
  "eventType": "USER_ACTIVITY", // Either "USER_ACTIVITY" or "ORG_ACTIVITY"
  "eventAction": "API_KEY_ADDED", // The specific action that occurred (see tables below)
  "organizationId": "12345678-abcd-1234-efgh-123456789012", // The organization where the activity occurred
  "userId": "87654321-dcba-4321-hgfe-210987654321", // The user who performed the action
  "userName": "Jane Smith", // Display name of the user
  "userEmail": "jane@example.com", // Email address of the user
  "userIPAddr": "192.168.1.100", // IP address of the user
  "payload": "{\"apiKeyName\":\"CI/CD Key\"}", // JSON string with event-specific details
  "timestamp": "2025-03-15T14:30:00.000Z" // ISO-8601 timestamp of when the event occurred
}
```

#### User Activity Types

When `eventType` is `USER_ACTIVITY`, the `eventAction` field contains one of the following values:

| Action | Description |
| - | - |
| `INVITE_USER` | A user was invited to the organization |
| `USER_INVITE_REVOKED` | A pending invitation was revoked |
| `REMOVE_USER` | A user was removed from the organization |
| `USER_JOINED_ORG` | A new user joined the organization |
| `USER_MODIFIED` | A user’s settings were changed |
| `USER_PASSWORD_MODIFIED` | A user’s password was changed |
| `USER_PREFERENCES_MODIFIED` | A user’s preferences were updated |
| `USER_CONVERTED_TO_SAML_IDP` | A user was converted to SAML-based SSO |
| `SCAN_STARTED` | A scan was started |
| `SCAN_COMPLETED` | A scan completed |
| `SCAN_ERRORED` | A scan encountered an error |
| `SCAN_REMOVED` | A scan was deleted |
| `INTEGRATION_ADDED` | An integration was added |
| `INTEGRATION_MODIFIED` | An integration was changed |
| `INTEGRATION_REMOVED` | An integration was removed |
| `INTEGRATION_START_AUTHORIZATION` | An integration authorization flow started |
| `APPLICATION_ADDED` | An application was added |
| `APPLICATION_MODIFIED` | An application was changed |
| `APPLICATION_REMOVED` | An application was removed |
| `APPLICATION_CONFIGURATION_UPDATED` | An application’s hosted scan configuration was updated |
| `APPLICATIONS_ADDED_FOR_REPOS` | Applications were created and added to repositories |
| `ENVIRONMENT_ADDED` | An environment was added |
| `ENVIRONMENT_MODIFIED` | An environment was changed |
| `ENVIRONMENT_REMOVED` | An environment was removed |
| `API_KEY_ADDED` | An API key was created |
| `API_KEY_REMOVED` | An API key was removed |
| `ALERT_RULE_TRIAGED` | An alert was triaged |
| `ALERT_RULE_REMOVED` | An alert rule was removed |
| `TECH_FLAG_ADDED` | A technology flag was added to an application |
| `TECH_FLAG_MODIFIED` | A technology flag was changed |
| `TECH_FLAG_REMOVED` | A technology flag was removed |
| `SCAN_CONFIG_MODIFIED` | A scan configuration was changed |
| `DOWNLOAD_SCAN_ASSET` | A scan asset was downloaded |
| `SUBSCRIPTION_MODIFIED` | A billing subscription was changed |
| `SUBSCRIPTION_ADDED` | A billing subscription was added |
| `ORG_DOWNGRADED` | The organization was downgraded |
| `ORG_MODIFIED` | The organization was modified |
| `ORG_SETTINGS_MODIFIED` | The organization settings were changed |
| `CUSTOM_TEST_SCRIPT_ADDED` | A custom test script was added |
| `CUSTOM_TEST_SCRIPT_REMOVED` | A custom test script was removed |
| `APPLICATION_POLICY_MODIFIED` | An application scan policy was changed |
| `ORGANIZATION_POLICY_ADDED` | An organization scan policy was added |
| `ORGANIZATION_POLICY_MODIFIED` | An organization scan policy was changed |
| `ORGANIZATION_POLICY_REMOVED` | An organization scan policy was removed |
| `ORGANIZATION_CONFIGURATION_ADDED` | An organization scan configuration was added |
| `ORGANIZATION_CONFIGURATION_MODIFIED` | An organization scan configuration was changed |
| `ORGANIZATION_CONFIGURATION_REMOVED` | An organization scan configuration was removed |
| `TEAM_ADDED` | A team was created |
| `TEAM_UPDATED` | A team was updated |
| `TEAM_DELETED` | A team was deleted |
| `REPO_MODIFIED` | A repository was updated |
| `REPO_REMOVED` | A repository was removed |
| `USER_SECRET_ADDED` | A user secret was created |
| `USER_SECRET_REMOVED` | A user secret was removed |
| `USER_SECRET_USED` | A user secret was referenced |
| `BUILD_OPEN_API_SPEC_REQUESTED` | An OpenAPI spec build was requested |
| `USER_PERCH_KEY_REQUESTED` | A Perch key was requested |
| `USER_PERCH_KEY_VALIDATED` | A Perch key was validated |

#### Organization Activity Types

When `eventType` is `ORG_ACTIVITY`, the `eventAction` field contains one of the following values:

| Action | Description |
| - | - |
| `EXTERNAL_ALERTS_TRIAGED` | Alerts were triaged by a third-party integration |

> **Note:** Some organization activity types are internal to StackHawk and are excluded from webhook delivery to prevent recursion. Only externally relevant events are sent.

## Feedback

Have any suggestions, feature requests, or feedback to share? [Contact StackHawk Support](https://docs.stackhawk.com/support/).