Configuring the Skytap Cloud webhook service for audit data

The Skytap Cloud webhook service provides Skytap Cloud account audit data in real time to a URL that you choose. Because the data is streamed continuously, you don’t need to query Skytap Cloud for updated information.

Currently, the webhook service provides account-wide auditing data, exactly the same data available from the administrator Auditing page, except in a real-time, continuous data stream.

Use the webhook service to create custom applications and reports. For example, if your organization uses scripts or other automation to add and remove VMs to a DNS server or Active Directory Domain server, the auditing webhook can provide environment data that the scripts can consume to automate these tasks.

To configure the auditing webhook
  1. Click Admin > Auditing to navigate to the Auditing page.
  2. Click Edit Webhook. The Configure Global Auditing Webhook dialog displays.

    auditing webhook

  3. Make sure Enabled is checked.
  4. Type the URL where the data will be sent. All audit events for the account will be sent to the destination URL.
  5. If the destination site is configured to use TLS encryption (optional, but strongly recommended), type or past the public Certificate.
  6. Click Save webhook.

If the destination URL is not available or stops responding, the webhook service will attempt to reconnect once per minute for up to six hours or 200 attempts. If it can’t reconnect, the webhook service will be disabled until you reconfigure it.

Skytap webhook data format

The webhook generates a JSON representation of all of the data available from the administrator Auditing report.

Example API Requests and responses

Request

GET /admin/webhooks

Response

[
    {
        "id": 123,
        "enabled": true,
        "url": "http://test.com/webhook",
        "certificate": ...,
        "type": "usage"
    },
    {
        "id": 456,
        "enabled": true,
        "url": "https://jenkins.test.com/webhook",
        "certificate": ...,
        "type": "audit"
    }
]

Request

GET /admin/webhooks/:ID

Response

{
    "id": 123,
    "enabled": true,
    "url": "http://test.com/webhook"
    "certificate": ...,
    "type": "usage"
}

Request

UPDATE /admin/webhooks/:ID

Response

{
    "id": 123,
    "enabled": true,
    "url": "http://test.com/webhook"
    "certificate": ...,
    "type": "audit"
}

Request

DELETE /admin/webhooks/:ID

Response

{"message": "success"}

Outbound Payload

{
  "version": 1,
  "message_id": "...", 
  "category": "auditing",
  "timestamp": "...",
  "Payload": [{
    "id": 12345678,
    "type": "Shutdown Environment",
    "type_code": "ShutdownConfigurationHistory",
    "date": "2018-08-27T14:38:13Z",
    "region": "US-Central",
    "payload": {},
    "user": {"id": null, "name": "auto_power_options"},
    "department": {"id": null, "name": null},
    "project": {"id": null, "name": null},
    "operation_id": "trn.3d22e5808c31013642ce6fab485f2413.91790.468/trn.5d5848a08c2f01af90ed0f6e7fb7101e.5711.156.1",
    "customer": {"id": 2, "name": "Super Users"},
    "operated_on": [
      {"resource_type": "environment", "name": "Database cluster", "id": 5572104, "guid": "configuration-1234567"},
      {"resource_type": "vm", "name": "Ubuntu 10.04 desktop", "id": 2832140, "guid": "vm-7654321-1234567"}
    ]
  }]
}