The Statusdashboard webhook notification method allows users to subscribe to webhook alerts for one or more services, which can be triggered automatically whenever creating or updating events. The webhook notification method configuration settings include global settings and status dashboard specific settings, both of which are described below:
Global Settings
Global webhook settings apply globally to a StatusDashboard account, including any status dashboards.
|
Option |
Description |
| Notifications |
Notifications > Webhook > Global Options > Notifications Enable / Disable Webhook Notifications When this option is disabled, the option to broadcast webhook messages when creating or updating events will not be available to StatusDashboard administrators but new webhook subscriptions to status dashboards will still be processed. Note: If your StatusDashboard 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.
|
Status Dashboard Settings
Status dashboard webhook settings apply to specific status dashboards (i.e. each status dashboard within an account has its own specific webhook settings.
|
Option |
Description |
| Dashboard Subscription |
Notifications > Webhook > Dashboard Specific Options > Dashboard Subscription > [Dashboard] Enable / Disable Webhook Subscriptions When this option is disabled, the webhook subscription option will not be available on the status dashboard. Note: If the account has reached the maximum number of webhook subscribers allowed, the webhook subscription option will not be available on any dashboard subscription pages.
|
Managing Webhook Subscriptions
The following options are available for managing webhook subscriptions, all of which are specific to individual status dashboards.
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 endpoint (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 Subscribe button on the dashboard page, select the webhook icon, click the manage button 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 |
Manual Subscribe Navigate to Notifications > Webhook > Dashboard Specific Options > Subscribers > [Dashboard]. 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 Endpoints Navigate to Notifications > Webhook > Dashboard Specific Options > Endpoints > [Dashboard]. From here, you may search, test, enable and delete endpoints as well as trigger management emails to the email address of record for a particular endpoint. Manage Subscriptions Navigate to Notifications > Webhook > Dashboard Specific Options > Subscribers [Dashboard]. From here, you may search subscribers, unsubscribe subscribers, confirm unconfirmed subscriptions, delete subscriptions and export the list of webhook subscribers. |
Notification Method Limits
The StatusDashboard webhook notification method has the following subscriber/message limits:
|
Subscriber Limits |
You can review how many confirmed webhook subscribers you have by navigating to Notifications > Webhook 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 > Webhook and viewing the webhook messages sent 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 > Webhook > Global 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 link.
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 subscription. 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 Subscribe button, 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:
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 notification method 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/event/123/"
}