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 webhooks and API reference guides to create custom applications for SaaS Alerts partners.  

Additional documentation

For complete documentation on subscription options, refer to the API documentation.

Setting up a SaaS Alerts Webhooks subscription

  1. Open manage.saasalerts.com.
  2. From the left navigation menu, navigate to Settings > API.
  3. Locate the Webhooks API section.
  4. To add a domain for subscription authorization, click the Add new domain icon.

  5. Enter a valid domain you will use for creating subscription endpoints.

    6. EXAMPLE  
    partnerdomain.com
    partnerdomain.com/path
    webhooks.partnerdomain.com

  6. Click Add to submit the domain for validation and add the domain authorization for a SaaS Alerts Webhooks subscription if validation is successful. 

    7. NOTE  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.

    IMPORTANT  The domain must match the location of your webhook endpoint. 

The domain validation process will produce one of the following results:

Retrieve the Webhooks API key by clicking SHOW KEY.

IMPORTANT  Click SHOW KEY only once. It can take up to 30 seconds for the key to be generated and presented.

NOTE  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.

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 indefinitely 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": "lorraine@somedomain.com"
      },
      "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"
    }
  ]
}

If the domain validation fails, 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. Also ensure put and get methods for the endpoint are enabled (example).

Partners may add multiple domains for the purposes of ingesting SaaS Alerts data to different platforms.