Webhooks

Use webhooks to receive notifications about events that occur in AppScan on Cloud.

Overview

User-defined HTTP callbacks (webhooks) are supported through the ASoC REST API. Webhooks notify you when events occur in AppScan on Cloud. The following event types are supported:

  • Scan execution complete
  • Application counters or status changed

To use webhooks, first download and install AppScan Presence in your local network (typically a one-time setup). Presence connects to ASoC.

When a webhook is triggered, Presence receives a command from ASoC and sends an HTTP GET request to the webhook URI in your local network.

Because Presence sends the request from within your network, you can notify internal servers without opening your firewall to incoming requests from ASoC.

Creating and managing webhooks using the REST API

To create, manage, and configure webhooks, use the ASoC REST API. The webhook endpoints are documented in the public API reference:

AppScan REST API - Webhooks endpoints

To create a webhook, send a POST request to the /api/v4/Webhooks endpoint with the following information:

  • PresenceId: The ID of the AppScan Presence instance that handles the webhook request
  • Uri: The HTTP endpoint to call when the event is triggered. The URI can include the {SubjectId} placeholder.
  • Event: The event type that triggers the webhook (ScanExecutionCompleted or ApplicationCountersChanged)
  • Global: A Boolean value that indicates whether this is a global webhook (applies to all applications or asset groups) or a scoped webhook (applies only to specific applications or asset groups)
  • AssetGroupId: (Optional) The ID of the asset group where the webhook applies

Example: Global webhook for scan completion

This example creates a global webhook that triggers when a scan execution completes. The webhook is called for all scans in the organization:

{
    "PresenceId": "1234",
    "Uri": "http://mysite.com/ScanEnded/{SubjectId}",
    "Event": "ScanExecutionCompleted",
    "Global": true
    }

When this webhook is triggered, ASoC sends a GET request to your service. The {SubjectId} value is replaced with the scan execution ID:

GET /ScanEnded/9ea1fcb6-dc1d-443a-bfff-7465ced2ef1b HTTP/1.1 
    Host: mysite.com

Important: The webhook does not send event data in the request body. To retrieve additional data (for example, the list of issues found in the scan), implement a separate service that handles the webhook event, logs in to ASoC using an API Key, and then retrieves the required data from the ASoC API.

Webhook URI placeholder

When you define a webhook URI, you can include the {SubjectId} placeholder. This placeholder is replaced with the ID of the event subject (typically the scan execution ID). You can use this value to pass basic event context to your webhook handler.

Example URI with placeholder:

Webhook URI: http://myservice.com/ScanEnded/{SubjectId}

If a scan execution with ID 9ea1fcb6-dc1d-443a-bfff-7465ced2ef1b completes, the webhook is called at:

http://mysite.com/ScanEnded/9ea1fcb6-dc1d-443a-bfff-7465ced2ef1b

Webhook access control

To create or modify a webhook, you must have the Create/Modify Webhooks permission in ASoC. By default, this permission is assigned to the Administrator and Manager roles, and it can also be added to Custom roles.

You can define a webhook at the organization level or for a specific asset group:

  • An organization-level webhook is defined and managed by an Administrator, or by a user with complete access to all groups.
  • An asset group-level webhook can be defined and managed by any user who has access to the asset group and the Create/Modify Webhooks permission.

Webhook scope

You can define a webhook as either global or scoped.

A Global webhook is triggered whenever an event that matches the webhook event type occurs in the organization or asset group (depending on where the webhook is defined).

A webhook that is not global can be associated with one or more Scopes. A scope can be a specific application or, if the webhook is defined at the organization level, a specific asset group.

A scoped webhook is triggered only when an event occurs within one of the associated scopes.

Example: If the webhook is triggered on scan execution completion and the scope is a specific application, the webhook is triggered each time a scan execution within that application completes.

Creating webhook associations for scoped webhooks

If a webhook is not global (that is, if you set "Global": false), you must create associations to specify which applications or asset groups the webhook applies to. Create these associations by using the webhook associations API endpoint.

To associate a webhook with specific applications or asset groups, send a POST request to the /api/v4/Webhooks/Associations/{id} endpoint, where {id} is the webhook ID returned when you created the webhook.

Example: Scoped webhook for a specific asset group

First, create a scoped webhook (not global):

{
    "PresenceId": "1234",
    "Uri": "http://mysite.com/ScanEnded/{SubjectId}",
    "Event": "ScanExecutionCompleted",
    "Global": false,
    "AssetGroupId": "5678"
    }

This webhook does not trigger until you create associations. Next, associate the webhook with specific applications by using the associations endpoint. This ensures the webhook is triggered only for scans of the associated applications within that asset group.

For details about creating and managing webhook associations, see the AppScan REST API documentation.