Webhooks (API Documentation)

What are webhooks?

At a high level, webhooks are automated messages sent from apps when something happens. 

In the context of SaaS Alerts, this means A Partner can receive a steady data stream of events as they are recorded by SaaS Alerts for Customer Organizations that belong to the Partner.  

 

This information is sent programmatically to a Partner application to act on as needed.  Setting up a Webhooks server to receive notifications and take custom actions for the Partner requires software development expertise.  

 

SaaS Alerts does not provide development assistance to Partners for the purposes of creating Custom Partner Applications that utilize webhook data feeds.  Experienced software developers who are familiar with webhooks concepts can use this guide along with SaaS Alerts Webhook and API reference guides to create custom applications for SaaS Alerts Partners. 

 

 

Setup a SaaS Alerts Webhooks subscription

1) Navigate to https://manage.saasalerts.com/ 

2) Navigate to “Settings” 

3) Within “Settings” scroll down to the Webhooks API 

4) To add a domain for subscription authorization press the ‘+’ button 

 

 

 

Enter a valid domain you will use for creating subscription endpoints example formats:

Examples:

“partnerdomain.com” 

“partnerdomain.com/path..”
“webhooks.partnerdomain.com”

 

Click Add Button

Pressing “Add” will submit the domain for validation and add the domain authorization for SaaS Alerts Webhooks subscriptions if validation is successful.  

 

Validation requires that when queried the domain returns a 2xx (typically 200) response indicating that it is live and can accept HTTP(s) requests. The domain host can have a blank page, API endpoint, or maybe the domain on which your primary website exists.

*The domain must match the location of your Webhook endpoint.  

 

The domain validation process will produce either:

“Domain validation succeeded” 

or

“Domain validation failed - unable to reach the specified domain.”

 

 

Domain validation succeeded

Retrieve the Webhooks API key by selecting “SHOW KEY”.

Press the “Show Key” Button once.  It can take up to 30 seconds for the key to be generated and presented.

The keys are self-managed and you can reset the key at any time.  When you reset the key you will be required to update your subscriptions with the new key.

You may now add subscriptions to push SaaS Alerts event data to your custom environment

Example:

Refer to the image example:

 

“https” and TLS security are required for any URL endpoint to receive a data feed.

Note - The “token” value is optional. When used it should be a security token generated by the partner.  If included, this token will be returned with each data stream to validate that the data is coming from the External Partner API - Processed Event Webhooks. 

Note: By default, subscriptions will work forever unless your server goes down, In this case, the app will try to reach it a few times and if not will be switched off.

Set Expiration Date and Time

 

 

Webhook Data Example

{
"partner": {
"id": "coThCxxb3wqZ6gnqYL57",
"name": "new partner"
},
"customer": {
"id": "oEqEYEmJOGUgwjXXzF9X",
"name": "cms_1911"
},
"product": {
"id": "1cjkEYV8DbfUgqhJ7pL3",
"name": "Microsoft"
},
"events": [
{
"time": "2021-06-04 13:00:02",
"user": {
"id": "2c17e55c-b189-4b21-a32a-04d071d1d9a2",
"name": "[e-mail]"
},
"ip": "184.90.129.41",
"location": {
"range": [
3092938752,
3092942847
],
"country": "US",
"region": "FL",
"eu": "0",
"timezone": "America/New_York",
"city": "Sanford",
"ll": [
28.7935,
-81.2868
],
"metro": 534,
"area": 10
},
"alertStatus": "low",
"jointType": "login.failure",
"jointDesc": "IAM Event - Authentication Failure",
"jointDescAdditional": "Agent - Edge / Method - Unknown / Activity - OAuth2:Authorize",
"eventId": "eafd522e-00e9-45aa-99bc-d142c8f78203"
}
]
}

 

Additional Documentation

For complete documentation on subscription options please visit:

 

https://app.swaggerhub.com/apis/SaaS_Alerts/external-partner-api/ 

 

 

Domain validation failed

If the domain validation fails, please check your domain to make sure that it can be publicly reached and will return a valid connection response. 

Note: When creating a subscription, the URL must be associated with the domain added in this step.  Please also ensure put and get methods for the endpoint are enabled.

 

For example https://datafeed.partnerdomain.com/path/to/feed.  Partners may add multiple domains for the purposes of ingesting SaaS Alerts data to different platforms.