AuditWolf Webhook Reference

Learn everything you need to know to get operational insights from AuditWolf events into your own applications.

A webhook is an HTTP callback that allows a web application to POST a message to a URL when certain events take place. Often called “reverse APIs", webhooks can be used to receive data in near real time, pass it on to another application, or process the data faster than traditional polling REST APIs.

AuditWolf supports webhooks for key events in the cloud management lifecycle of your Azure resources. The different categories of events include:

  • Issues detected or resolved
  • Cloud resources have changed
  • Cloud costs have changed
  • Audit score has changed

Event triggers

Issues detected or resolved

  • task.create : An new issue was detected and a work item task was created.
  • task.suppress : An existing task was suppressed.
  • task.complete : An existing task was completed and the issue has been resolved.

Cloud resources have changed

  • resource.create : A new cloud resource was detected in Azure.
  • resource.change : A change was detected in an existing cloud resource in Azure.
  • resource.delete : An existing cloud resource was deleted from Azure.

Cloud costs have changed

  • costs.overrun : AuditWolf is predicting you are about to go (or have gone) over budget.
  • costs.savings : AuditWolf has detected potential cloud waste and is offering new saving recommendations for your cloud resources.

Audit score has changed

  • auditscore.up : Your overall AuditWolf Audit Score has improved. This is a % value.
  • auditscore.down : Your overall AuditWolf Audit Score has decreased. This is a % value.

AuditWolf webhook event payload

AuditWolf posts to callback URLs with a JSON payload for the event. This payload includes the following fields:

  • awid : Your AuditWolf Account Id
  • id : A unique id for this event
  • objectid : The id of the underlying AuditWolf object this event relates too. ie: A task, cloud resource, cost analysis etc
  • type : The webhook event type that triggered this event (see previous section)
  • timestamp : A UTC based timestamp of when this event was originally created 
  • subscriptionId : The Azure subscription that the resource belongs to for this event
  • resourceId : The Azure resource Id
  • resourceName : The Azure resource name
  • summary : The message/data related to this event.
  • severity : The severity of this event. Can be HIGH, MEDIUM, LOW or INFO
  • uri : The fully qualified URL to view this object in the AuditWolf portal.

Below is sample of a task.create event payload:

{
     "awid": "28878173-1d37-432b-a3e3-faeaeb62f1d1",
     "id": "d9d41ada-c2be-4643-87f3-c73980257fdd",
     "objectid": "80ce9fa0-c865-4460-aeed-43c9ac534474",
    "type": "task.create",
     "timestamp": "2019-01-14T23:28:56.782Z",
     "subscriptionId": "a8bd955b-86f8-4413-919d-a89910462c04",
     "resourceId": "/subscriptions/.../providers/Microsoft.Web/sites/webApp01",
     "resourceName": "webApp01",  
    "summary": "Configure the webApp01 web app service to use more than one instance.",
     "severity": "MEDIUM",
     "uri": "https://portal.auditwolf.com/tasks/80ce9fa0-c865-4460-aeed-43c9ac534474"    
}

Securing your webhook

To help assure integrity of your events coming from AuditWolf, efforts have been made to secure your webhook payload:

  1. AuditWolf will only send events over HTTPS, and the endpoint configured must have a valid digital certificate.
  2. AuditWolf digitally signs all events.  

The digital signature is a base64 encoded HMAC SHA256 hash created using your shared secret against the payload message. 

The resulting hash is stored in the x-auditwolf-webhook-sig header of the POST. 

If you wish to verify that the incoming event to your callback URL is actually coming from AuditWolf and hasn't been tampered with you should verify the digital signature before processing it.

NOTE: Your shared secret was generated for you in the AuditWolf Portal during webhook creation, and provided to you when you saved it. If you lose it, to generate a new shared secret you will need to create a new webhook and delete the old one. 

Error Codes

You can review all delivery logs of your webhooks directly in the AuditWolf Portal under Event Logs.

Here are common error codes and their meaning:

  • 0 : An unknown error has occurred. You should probably reach out to AuditWolf support for help.
  • 200 : Event delivered OK
  • 401 : Unauthorized. Your server isn't allowing us to connect.
  • 408 : Can't complete the request. The server may have timed out, or isn't reachable. Check the Reason field for more details of the failure.
  • 50x : Server error occurred. Check the logs on your end. 

NOTE: AuditWolf will automatically time out if the latency of the connection is longer than 15 seconds.