Webhooks

Webhooks can be used to receive notifications about events that occur in AppScan on Cloud.

User-defined HTTP callbacks - or webhooks - are supported through the ASoC REST API. Two types of event are supported:
  • Scan execution complete
  • Counters or status of an application changed
To use webhooks you must first download and install an AppScan Presence to your local network (usually a one-time process). The Presence is connected to ASoC.

When a webhook is initiated, the Presence gets a command from ASoC, and sends an HTTP GET request to the URI set for the webhook in the local network.

Due to the Presence, this HTTP request can be sent to servers within the organization without needing to open the firewall to incoming requests from ASoC.

You define the webhook so that when the event you want is triggered, the Presence will initiate a GET request to a URI. The URI can contain a place holder, {SubjectId}, that will be replaced with the ID of the event’s subject.

Example:

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

Event type: "Scan execution complete"

Trigger is Scan Execution with ID: 9ea1fcb6-dc1d-443a-bfff-7465ced2ef1b

The request sent will then be:
GET /ScanEnded/9ea1fcb6-dc1d-443a-bfff-7465ced2ef1b HTTP/1.1 
Host: myservice.com 
Note that the webhook does not send any data related to the event. To get data (such as the list of issues found by in the scan), you would need to implement a separate service that, when handling the event, will login to ASoC using an API Key and retrieve the required data from ASoC API.

Webhook access control

To create or modify a webhook, you need “Create/Modify Webhooks” permissions in ASoC, which by default are assigned to Administrator and Manager roles, but which can also be added to Custom roles.

A webhook can be defined either at 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 with access to the Asset Group, who has permission to Create/Modify Webhooks.

Webhook scope

A webhook can be defined as either Global or Scoped.

A Global webhook will be triggered whenever an event that matches the webhook’s event type occurs (in the Organization, or Asset Group, as defined.

A webhook that is not defined as Global, can be associated with one or more Scopes. A Scope can be a particular Application or, if the webhook is defined at Organization level, the scope can be a specific AssetGroup.

A scoped webhook will be triggered only if an event occurs under one of the associated scopes.

For example, if the webhook is set to be triggered upon “Completion of scan execution”, and the Scope of the webhook is a specific Application, the webhook will be triggered each time a scan execution within that application is completed.