Webhooks Integration Notifications / Webhooks Integration

The Statusdashboard webhook integration allows your users or customers to subscribe to webhook alerts, which can be triggered automatically whenever creating or updating events on your status dashboard.  The webhook integration settings can be accessed by navigating to Notifications > Webhooks and then selecting the Options menu in the upper right.

Activating the Webhook Integration

The webhook integration may be enabled/disabled by navigating to Notifications > Webhooks > Options > Enable/Disable and changing the Enable Event Webhooks toggle button.  When this option is disabled, the option to broadcast webhook messages when creating or updating events will not be available but new webhook subscriptions will still be processed.  Additionally, if your account has reached the maximum number of allowed webhook messages for the current month, the broadcast webhook option will not be available when managing events.

Enabling Webhook Subscriptions

New webhook subscription requests may be enabled/disabled on the status dashboard by navigating to Notifications > Webhooks > Options > Enable/Disable and changing the Enable Webhook Subscriptions toggle button.  When this option is disabled, the webhook subscription option will not be available on any dashboard subscription pages.  Additionally, if your account has reached the maximum number of confirmed webhook subscribers allowed, the webhook subscription option will not be available on any dashboard subscription pages.

Configuration Options

Option

Path

Description

Webhook Instructions

Notifications > Webhooks > Options > Instructions

If you would like to present your webhook subscribers with any special instructions or information about how you will use the webhook integration, enter them in the webhook instructions field.  Instructions will be presented on all webhook subscription screens on your dashboard.


Managing Webhook Subscriptions

Note: Webhook URLs are tied to a single management email address. A single email address can only be used to manage a single webhook URL (i.e. one email address cannot be used to manage multiple webhook urls).

End Users

Subscribe:

Navigate to the dashboard, click the Subscribe button on the dashboard page and select the webhook icon.  Enter a valid email address and webhook URL and select one or more services to subscribe to. We'll send a confirmation email with a validation link which when clicked, will confirm the subscriptions. Once confirmed, the webhook URL will be subscribed to event webhook messages and will receive any relevant alerts that you broadcast when managing events.


Manage Subscriptions:

Navigate to the dashboard, click the Manage Subscriptions link in the footer, select the webhook icon and provide a valid email address (one that was previously registered with a webhook URL). We'll send a validation email which will provide access to add and/or delete subscriptions to specific services on the dashboard. You'll also be able to re-enable a disabled endpoint, and refresh the webhook signing key.

StatusDashboard Administrators

Subscribe:

Navigate to Notifications > Webhooks > Options > Subscriber Add.  Any webhook URLs added here will be immediately subscribed to the associated services.  Please be aware that these manually added webhook URLs can be unsubscribed from alerts through the standard StatusDashboard unsubscribe process by your end users.


Manage Subscriptions:

Navigate to Notifications > Webhooks > Options > Subscriber List.  From here, you may search subscribers, unsubscribe subscribers, confirm unconfirmed subscriptions, delete subscriptions and export the list of webhook subscribers.


Integration Limits

The StatusDashboard webhook integration has the following subscriber/message limits:

Subscriber Limits

You can review how many confirmed webhook subscribers you have by navigating to Notifications > Webhooks and viewing the Webhook Subscribers information field.

Message Limits

You can review how many webhook messages you have sent in the current month by navigating to Notifications > Webhooks and viewing the Event Webhooks Sent (this month) information field.


Webhook Delivery Reports

StatusDashboard maintains a record of every webhook message sent including the HTTP response code that we receive from the endpoint, and the webhook payload that we deliver.  If you would like to review a record of sent webhook messages for your account, you may do so by navigating to Notifications > Webhooks > Options > Delivery Report.

Webhook Delivery Errors

If we experience any errors in delivering a webhook message to a subscribed endpoint (for example, connectivity errors, or a non-HTTP200 response), we will disable the endpoint and will not attempt further delivery until the subscriber takes action. Additionally, we will send the subscriber an email notification that the endpoint has been disabled. Subscribers can re-enable an endpoint by following the manage webhook instructions.

Webhook Verification

Webhooks can be verified as authentic using the following methods:

Source IP Address

IP addresses from which we will send webhook messages are listed in our public StatusDashboard configuration file.  This file is updated whenever our IP addresses change.

Webhook Signature

StatusDashboard includes an HTTP header with each webhook POST request to each endpoint: X-StatusDashboard-Signature.  Each webhook request that is sent to each endpoint contains the unique signature for that request.  To verify a webhook request, you must generate a signature using the same key that StatusDashboard uses and compare that to the value of the X-StatusDashboard-Signature header.

The unique webhook key that is used to generate and validate the request can be obtained by browsing to the dashboard where the subscription was made, selecting the manage subscriptions link in the footer, selecting the webhook icon, and entering the email address that was used to subscribe the webhook endpoint.  We'll immediately send you an email that contains all current webhook subscriptions that are linked to this email address, as well as the current webhook key.

The webhook signature is calculated using the following methodology:

  1. Combine the webhook endpoint URL (the url that is accepting the webhook) with the webhook payload.
  2. Hash the resulting string with HMAC-SHA1 using your webhook key to generate a binary signature.
  3. Base64 encode the binary signature.
  4. Compare the signature that you generated with the one provided in the X-StatusDashboard-Signature header.  If the signatures match, then the webhook is authentic.

An example signature verification utilizing Python is shown below:

import hmac
from hashlib import sha1
from base64 import b64encode

# Assumes that we received an X-StatusDashboard-Signature header value and stored it in
# the variable: webhook_signature

# Our webhook key (provided by StatusDashboard)
key = '1fa62c6e4985457995f541a831feb6db'

# Our webhook endpoint URL
url = 'https://www.acme.com/webhooks/statusdashboard'

# Combine the webhook endpoint URL with the payload that we received from StatusDashboard
s = url + request.body

Hash the string with our key and produce a digest
s_hmac = hmac.new(key, s, sha1).digest()

# Base64 encode the digest
signature = b64encode(s_hmac)

# Check if our signature matches the one provided by StatusDashboard
if signature == webhook_signature:    
    # Do something
else:    
    # Do something


Webhook Payload

The webhook integration will deliver a JSON payload consisting of the dates/times of the event type, the event dates (in ISO 8601 format), the event description, services impacted by the event, event status and any event updates. An example payload is shown below:

{    
    "coordinator": "",
    "description": "We will be performing routine system patching of the Exchange Server.  Email client connectivity may be impacted during the maintenance period.",    
    "end": "2016-07-01T16:00:00Z",    
    "id": 123,
    "impact": "",
    "services": [        
        {            
            "description": "Corporate email server servicing North America.",            
            "group": "South Campus",            
            "id": 4004,            
            "name": "Exchange Server"        
        }    
    ], 
    "severity": "minor_performance",
    "start": "2016-07-01T15:00:00Z",    
    "status": "started",    
    "timeline": [        
        {            
            "date": "2016-07-01T15:00:00Z",
            "status": "started",            
            "update": "The maintenance is beginning."        
        }
    ]
    "type": "maintenance",    
    "url": "http://status.acme.com/incident/detail?i=123",
}


Required Permissions Role: Administrator or Notifications