The StatusDashboard Webhook integration allows incident events to be created and updated automatically in your StatusDashboard environment whenever incidents are created and updated in third party applications (e.g. ServiceNow) - this includes automatically updating any relevant status dashboards, and broadcasting notifications to subscribers.
The Webhook integration settings can be accessed in the StatusDashboard administration portal by navigating to: Integrations > Webhook (inbound).
How it works
The integration works by configuring your application to send webhooks to a custom StatusDashboard endpoint whenever an incident is created or updated in your application. The webhook your application sends will contain important information about the event like a unique application event ID, one or more application services, and basic information about the incident event. StatusDashboard uses this information to manage a corollary event in your StatusDashboard account, and to notify your customers when changes happen (if configured to do so).
Configuration
In order to configure your StatusDashboard account to receive webhooks sent from third party applications, login to the StatusDashboard administration portal and navigate to Integrations > Webhook (inbound). The StatusDashboard configuration options are shown below:
Integration Settings
| Setting | Value |
| Webhook Endpoint |
This is the unique webhook endpoint that is attached to your StatusDashboard account to which integration webhooks should be sent. Note: If the webhook endpoint is regenerated, it will need to be updated in the system responsible for generating and sending the webhooks.
|
| Webhook Secret |
A webhook secret can be used to sign all webhooks that are sent from third party applications (see below for an example of how to sign a webhook). If webhooks are signed, StatusDashboard will use the signature to validate that the webhook came from your account and is valid. If the webhook secret is enabled and a webhook is received with an invalid signature, it will be rejected. Customers are highly encouraged to utilize webhook signatures. |
| External Service Ids |
If you need to send webhooks with service ids from your third party applications instead of StatusDashboard service ids, you can enable service id mapping. Once enabled, you can add an external service id to any StatusDashboard service so that when inbound webhooks are received, the correct StatusDashboard services are included in events and notifications. |
|
IP Whitelist |
Create and enable an IP or network address whitelist to block acceptance of webhooks except from approved source ip addresses. When the IP whitelist is enabled, inbound webhooks will only be accepted from the listed, active IP or network addresses. |
|
Notifications (optional) |
Notifications can be sent to subscribers whenever incident events are created or updated by an integration webhook. Note: Only enabled notification methods will be shown here. If a notification method is not shown, it must be configured and enabled first.
|
Service Settings
The impacted services that are sent in the webhook payload can either be StatusDashboard service ids, or external service ids. External service ids would be used when a third party system has its own name or id for services and you need/want to map those to StatusDashboard services when that third party system created events. When utilizing external services, the third party application's service ID must be added to the corresponding StatusDashboard service by navigating to Services > Edit > Webhook (inbound) > Service ID in the StatusDashboard administration portal.
Important Considerations
- StatusDashboard currently only supports the creation of incident events via inbound webhooks - all other event types are ignored.
- When a third party application sends a webhook to StatusDashboard, the third party application's event ID is set on the StatusDashboard event. This event ID is used when subsequent webhooks are received from the application to identify the event in StatusDashboard. This event ID must be unique among your events in StatusDashboard.
- Events created by third party applications via webhooks can still be updated manually by StatusDashboard administrators in the StatusDashboard administration portal.
- When an incident event is initially created via an inbound webhook, regardless of the status, the start time of the incident is the time the webhook is received by StatusDashboard. The start time cannot be modified via inbound webhooks.
- When an incident event is updated via an inbound webhook with a status of 'resolved', the end time of the event is the time the webhook is received by StatusDashboard. The end time cannot be modified via inbound webhooks. To re-open an event, set the status to anything other than 'resolved' via a webhook update.
Webhook Format
The required webhook format is a json payload with the following key/value pairs, some of which are required, and some of which are optional.
Required Values
| Key | Value |
|
id string |
The unique id that identifies the event in the third party application. Maximum Length: 32 characters |
|
type string |
The type of event. If an unsupported event type is received, the webhook will be discarded. Supported values:
|
|
status string
|
The current status of the event. Supported values:
Note: The status of an event should be kept in sync with the status included on any updates (although this is not mandatory). For example, when updating the status of an event to 'monitoring', the update status and the event status should both be set to 'monitoring'. This will provide a coherent incident timeline for customers when viewing the event on the status dashboard.
|
|
description string |
The description of the event. Maximum Length: 5,000 characters |
|
services array of strings or array of integers |
The list of service ids that this event impacts. If service mapping is enabled, then these service ids are those of the third party application and must be represented as strings. The service ids must be mapped to StatusDashboard services as described above. If any of the services received in the webhook do not have a corresponding mapping to a StatusDashboard service, the webhook will be discarded. If service mapping is disabled, then these service ids are StatusDashboard service ids and must be represented as integers. Maximum Length:
|
Optional Values
| Key | Value |
|
update dictionary |
An update for the event, in the following format: {'status':'identified', 'update':'We have identified the problem'}
Supported values (status):
Maximum Length:
Note: The update attribute is relevant ONLY when updating an existing event and is ignored on new events.
|
|
timeline boolean |
When set to True on a newly created event where the status is 'investigating', an event update timeline entry will be created with a status of 'investigating'. This attribute should be used if you are creating a timeline that tracks the progression of incidents from investigating to resolved. When omitted, there will not be an event timeline, unless you create timeline updates with the 'update' attribute. |
|
severity string |
The severity of the event can be either the StatusDashboard standard supported values, or custom severity values: Standard Values
Custom Values Custom severity values can be configured by navigating to Events > Event Configuration. Any custom severity levels defined in the event configuration can be submitted with an inbound webhook. Note: If you have custom severity levels enabled in the event configuration, you cannot use the standard values.
|
|
severity_hide boolean |
Whether or not to hide the severity value from any status dashboards and event notifications. Severity should be set to hidden in the case where you want to track severities internally but do not want to display them to your customers. |
|
impact string |
The impact analysis of the event. Maximum Length: 1,000 characters |
|
coordinator string |
The coordinator for the event. Maximum Length: 250 characters |
|
suppress_notif boolean |
Whether or not to suppress notifications to subscribed users when this webhook is received. This attribute can be used to selectively suppress notifications when the StatusDashboard inbound webhook configuration is set to send them. When creating or updating events, if the suppress_notif attribute is included in the webhook and set to True, no notifications will be sent for that particular received webhook. |
Webhook Signature
The webhook signature can be created manually, or it can be created via the signature endpoint.
- Manual Signature Calculation: To create the signature manually, you must concatenate the full webhook url endpoint (https://www.statusdashboard.com/webhooks/integration/{endpoint}/) and the webhook payload (as a string) and then digest it with SHA256. An example of performing this action is shown below.
- Automated Signature Calculation: If you lack the ability to calculate the signature manually within a third party application, you can use the signature calculation endpoint to perform this action automatically by sending the webhook payload to the endpoint (https://www.statusdashboard.com/webhooks/integration/{endpoint}/signature) along with your webhook secret in the x-statusdashboard-secret header.
Example: Automated Signature Calculation
To create a webhook signature automatically, send the full webhook payload, including the webhook secret, to the signature calculation endpoint: https://www.statusdashboard.com/webhooks/integration/{endpoint}/signature.
The following Python example demonstrates how to automatically calculate the webhook signature for a given webhook payload:
#!/usr/bin/python3
import hmac
import json
from hashlib import sha256
from base64 import b64encode
import requests
secret = 'e1d4c3e0f6b64c5f8eb676aef6f502f4'
endpoint = 'a183eb2c79ec4e898002275aefc78826'
url = f'https://www.statusdashboard.com/webhooks/integration/{endpoint}/'
# Webhook payload
webhook_payload = {
'id': '885354',
'type': 'incident',
'status': 'investigating',
'description': 'We are currently experiencing an issue with network connectivity.',
'services': ['3ksf32', '4jf891']
}
# Send the request
try:
response = requests.post(
url,
data=json.dumps(webhook_payload),
headers={'Content-Type': 'application/json', 'x-statusdashboard-secret': secret},
verify=True
)
except Exception as e:
print('Error sending request: %s', e)
# Obtain the signature
response_json = response.json()
signature = response_json['signature']
# Now use the 'signature' to send the signed webhook.
Example: Event Management
The below examples demonstrate management of an event using inbound webhooks. All examples utilize Python and send signed webhook requests. In these examples, the third party system has created an event id of 88534 and there are two services within the third party system that have been mapped to StatusDashboard services, with ids 3ksf32 and 4jf891.
All examples will utilize the following Python program to send the webhook. If you plan to utilize this Python program, note the following:
- This program assumes webhook signatures will be utilized.
- You will need to substitute the secret and endpoint variables for the values from your StatusDashboard account.
- This program assumes that external service mapping is being utilized. If you do not want to use external service mapping, then change the services list to include StatusDashboard service ids from your StatusDashboard account.
- Substitute the webhook_payload for the webhook_payload provided in each example.
#!/usr/bin/python3
import hmac
import json
from hashlib import sha256
from base64 import b64encode
import requests
secret = 'e1d4c3e0f6b64c5f8eb676aef6f502f4'
endpoint = 'a183eb2c79ec4e898002275aefc78826'
url = f'https://www.statusdashboard.com/webhooks/integration/{endpoint}/'
# Add a relevant payload
webhook_payload = {}
# Convert the payload to a string
s_webhook_payload = json.dumps(webhook_payload)
# Calculate the signature
s = url + s_webhook_payload
s_hmac = hmac.new(
bytes(secret, 'utf-8'),
bytes(s, 'utf-8'),
sha256
).digest()
signature = b64encode(s_hmac)
# Send the webhook
try:
response = requests.post(
url,
data=s_webhook_payload,
headers={'Content-Type': 'application/json', 'x-statusdashboard-signature': signature},
verify=True
)
except Exception as e:
print('Error sending webhook: %s', e)
Create Event
In this example, the event is initially created.
webhook_payload = {
'id': '885354',
'type': 'incident',
'status': 'investigating',
'description': 'We are currently experiencing an issue with network connectivity.',
'services': ['3ksf32', '4jf891']
}
Update Event (identified)
In this example, the issue has been identified, and the event status is changed to identified.
webhook_payload = {
'id': '885354',
'type': 'incident',
'status': 'identified',
'description': 'We are currently experiencing an issue with network connectivity.',
'services': ['3ksf32', '4jf891'],
'update': {'status':'identified', 'update':'We have identified the problem as a faulty router. We expect resolution shortly.'}
}
Update Event (monitoring)
In this example, the issue has been resolved, and the team is monitoring.
webhook_payload = {
'id': '885354',
'type': 'incident',
'status': 'monitoring',
'description': 'We are currently experiencing an issue with network connectivity.',
'services': ['3ksf32', '4jf891'],
'update': {'status':'monitoring', 'update':'The faulty router has been replaced, and networking has been restored.'}
}
Update Event (resolved)
In this example the incident has been fully resolved.
webhook_payload = {
'id': '885354',
'type': 'incident',
'status': 'resolved',
'description': 'We are currently experiencing an issue with network connectivity.',
'services': ['3ksf32', '4jf891'],
'update': {'status':'resolved', 'update':'Networking has been fully restored and verified. This incident is now fully closed.'}
}