Integrations

Getting PingSafe Events on Webhook

Steps on integrating PingSafe with custom webhook to create incidents of security alerts.

In case a user wants to receive incidents of security alerts on their custom webhook instead of the other alerting service integrations available via PingSafe, they have the option to do so through PingSage webhook integration. PingSafe takes special care to ensure that the integration channel is secure and events being sent to the webhook can’t be spoofed without the API key. 

 

Steps to integrate your custom webhook with PingSafe

  1. Login to PingSafe AI. Click on your user profile(marked within the circle). Click on Settings
  2. In the settings tab under the Integrations section, click on Webhook.
  3. Click on Add Webhook.
  4. Enter a valid HTTPS custom webhook URL along with a randomly generated API key.
  5. Webhook events can be triggered automatically by turning the “Auto Mode” on or manually from the issue page. 

 

Steps to consume PingSafe alert incidents on custom webhook

PingSafe will send a JSON to your custom webhook in the format shown below along with a checksum header called `X-PingSafe-Checksum`


{

“event”: <base64_encoded_data>

}
  1. Validate the authenticity of the received data using your secret API. The SHA256 hash of the base64 encoded data along with the API key with a dot (.) delimiter should match the checksum header (X-PingSafe-Checksum) passed by PingSafe.
    SHA256(<base64_encoded_data>.<API_KEY>)
  2. Decode `base64_encoded_data` to get your alert incident data.
  3. The decoded data will follow the structure as below:

Name

Type

Description

Mandatory

id

string

Unique ID generated by PingSafe for each issue

Yes

severity

string

Severity of the issue, can be “HIGH”, “MEDIUM” or “LOW”

Yes

message

string

A short message describing the issue

Yes

description

string

Detailed description of the security issue

Yes

recommendedAction

string

Steps to remediate the issue

No

impact

string

Impact of the issue

No

infoLink

string

Link to PingSafe knowledgebase to learn more about the issue

No



pluginKey

string

A unique identifier representing the category of the issue

Yes

pluginTitle

string

Summary of the issue

Yes

issueUrl

string

Link to the issue in PingSafe dashboard

Yes

newResources

Array of Resource

A list of newly discovered resources for an issue (only populated with Auto Mode event triggers)

No

affectedResources

Array of Resource

A list of all resources for a given issue

Yes

 

The Resource object will follow the structure as below:

Name

Type

Description

Mandatory

accountId

string

Unique identifier for the cloud account for the associated resource

No

accountTitle

string

Name of the cloud account for the associated resource

No

accountProvider

string

Cloud provider for the associated resource. Can be “AWS”, “AZURE” or “GOOGLE”

No

region

string

The region the resource is present in 

No

subdomain

string

Affected subdomain

No

appIdentifier

string

Affected App Indentifier

No

appVersion

string

Affected App Version

No

resourceId

string

Unique ID generated by PingSafe for each resource

Yes

resourceType

string

A unique identifier representing the category of resource

No

meta

Object

Additional metadata of the resource

No