Webhook Notification

Webhook Notifications

StatusCast can send notifications to your users via webhooks when you create, update or resolve an incident. Webhooks contain information about your event similar to how the StatusCast API returns event results when queried. Subscribers can add a webhook URL when initially signing up:

Or if they have a user account, they can add this URL to their subscription whenever they would like:

Webhook Basics

Webhooks are HTTP POST requests that StatusCast's servers send to the specified endpoint. Webhook data, in a JSON format, contains information relative to an incident posted, updated, or resolved. A webhook from StatusCast will contain all information relative to an incident that has been posted including but not limited to the affected component(s), the current status of affected components, the event title, the date/time that the event started, and all posts associated.

Endpoints are required to respond with a 2xx response code (3xx is considered a failure), and must respond within 30 seconds of initial connection. If StatusCast is unable to communicate with your endpoint it will retry up to 4 more times.

Slack and MS Teams

If you are using Slack or MS Teams, simple use the webhook URL generated by your chosen channel to subscribe. Both of these applications have an expected Webhook format and StatusCast will automatically conform to that requirement as long as your webhook URL points to Slack or MS Teams(Teams URLs should point to office.com)

Webhook Examples

New Incident

{
  "CurrentComponentStatus": [
    {
      "ComponentId": 456570,
      "Status": "Unavailable",
      "DateChanged": "2023-03-21T20:33:47"
    },
    {
      "ComponentId": 501142,
      "Status": "Unavailable",
      "DateChanged": "2023-03-21T20:33:47"
    }
  ],
  "PreviousComponentStatus": [
    {
      "ComponentId": 456570,
      "Status": "Unavailable",
      "DateChanged": "2023-03-21T20:33:47"
    },
    {
      "ComponentId": 501142,
      "Status": "Unavailable",
      "DateChanged": "2023-03-21T20:33:47"
    }
  ],
  "Id": 417149,
  "DateCreated": "2023-03-21T20:34:11.18",
  "IncidentType": "ServiceUnavailable",
  "Status": "InProgress",
  "Title": "The Ring is Missing",
  "StartDate": "2023-03-21T20:33:47",
  "EndDate": null,
  "ShortUrl": null,
  "ExternalId": "",
  "EstimatedDurationMinutes": null,
  "Posts": [
    {
      "Id": 896335,
      "Text": "<p>We need help finding it<br></p>",
      "Date": "2023-03-21T20:33:47",
      "IsPublished": true,
      "PostType": "Informational",
      "NewComponentStatus": "Unavailable",
      "CustomFieldList": []
    }
  ],
  "AffectedComponents": [
    {
      "ComponentId": 501142,
      "ComponentName": "The One Ring",
      "IconImageSrc": null,
      "DirectlyEffected": true
    },
    {
      "ComponentId": 456570,
      "ComponentName": "Three Rings for Elven Lords",
      "IconImageSrc": null,
      "DirectlyEffected": false
    }
  ],
  "CustomFieldList": [],
  "Groups": [
    131636,
    132052,
    132063
  ]
}

Updated Incident with a new status

{
  "CurrentComponentStatus": [
    {
      "ComponentId": 436949,
      "Status": "DegradedPerformance",
      "DateChanged": "2024-09-26T13:58:08.568339Z"
    },
    {
      "ComponentId": 436953,
      "Status": "DegradedPerformance",
      "DateChanged": "2024-09-26T13:58:08.5683394Z"
    },
    {
      "ComponentId": 436952,
      "Status": "DegradedPerformance",
      "DateChanged": "2024-09-26T13:58:08.5683396Z"
    }
  ],
  "PreviousComponentStatus": [
    {
      "ComponentId": 436949,
      "Status": "Unavailable",
      "DateChanged": "2024-09-26T13:58:08.6205669Z"
    },
    {
      "ComponentId": 436953,
      "Status": "Unavailable",
      "DateChanged": "2024-09-26T13:58:08.6205675Z"
    },
    {
      "ComponentId": 436952,
      "Status": "Unavailable",
      "DateChanged": "2024-09-26T13:58:08.6205677Z"
    }
  ],
  "Id": 567955,
  "DateCreated": "2024-09-26T13:57:19.263",
  "IncidentType": "ServiceUnavailable",
  "Status": "InProgress",
  "Title": "Full Outage alert for Email, Chat",
  "StartDate": "2024-09-26T13:57:00",
  "ShortUrl": "https://sta.ac/u/lZziBnNL",
  "ExternalId": "",
  "Posts": [
    {
      "Id": 1252642,
      "Text": "<p>Mercury services are currently experiencing a degradation of service that may impact customers. If your service is impacted, then your organization will be notified. If you are unable to access your application and have not received a notification, please ensure your organization is not blocking mail from [email protected].&nbsp;<br></p>",
      "Date": "2024-09-26T13:57:00",
      "IsPublished": true,
      "PostType": "Informational",
      "NewComponentStatus": "Unavailable",
      "CustomFieldList": []
    },
    {
      "Id": 1252643,
      "Text": "<p>We've done something and now the application is just slow and not down!<br></p>",
      "Date": "2024-09-26T13:58:00",
      "IsPublished": true,
      "PostType": "Informational",
      "NewComponentStatus": "DegradedPerformance",
      "CustomFieldList": []
    }
  ],
  "AffectedComponents": [
    {
      "ComponentId": 436949,
      "ComponentName": "Communication channels",
      "IconImageSrc": "https://statuscastsaprdeast.blob.core.windows.net/pages/21225/001ba6fc4474487bb4390b53c9c3fcfa",
      "DirectlyEffected": false
    },
    {
      "ComponentId": 436953,
      "ComponentName": "Chat",
      "DirectlyEffected": true
    },
    {
      "ComponentId": 436952,
      "ComponentName": "Email",
      "DirectlyEffected": true
    }
  ],
  "CustomFieldList": []
}

Resolved Incident

{
  "CurrentComponentStatus": [
    {
      "ComponentId": 436949,
      "Status": "Available",
      "DateChanged": "2024-09-26T14:01:34.0073485Z"
    },
    {
      "ComponentId": 436953,
      "Status": "Available",
      "DateChanged": "2024-09-26T14:01:34.0073489Z"
    },
    {
      "ComponentId": 436952,
      "Status": "Available",
      "DateChanged": "2024-09-26T14:01:34.0073491Z"
    }
  ],
  "PreviousComponentStatus": [
    {
      "ComponentId": 436949,
      "Status": "DegradedPerformance",
      "DateChanged": "2024-09-26T14:01:34.0628831Z"
    },
    {
      "ComponentId": 436953,
      "Status": "DegradedPerformance",
      "DateChanged": "2024-09-26T14:01:34.0628836Z"
    },
    {
      "ComponentId": 436952,
      "Status": "DegradedPerformance",
      "DateChanged": "2024-09-26T14:01:34.0628837Z"
    }
  ],
  "Id": 567955,
  "DateCreated": "2024-09-26T13:57:19.263",
  "IncidentType": "ServiceUnavailable",
  "Status": "Closed",
  "Title": "Full Outage alert for Email, Chat",
  "StartDate": "2024-09-26T13:57:00",
  "EndDate": "2024-09-26T14:01:00",
  "ShortUrl": "https://sta.ac/u/lZziBnNL",
  "ExternalId": "",
  "Posts": [
    {
      "Id": 1252642,
      "Text": "<p>Mercury services are currently experiencing a degradation of service that may impact customers. If your service is impacted, then your organization will be notified. If you are unable to access your application and have not received a notification, please ensure your organization is not blocking mail from [email protected].&nbsp;<br></p>",
      "Date": "2024-09-26T13:57:00",
      "IsPublished": true,
      "PostType": "Informational",
      "NewComponentStatus": "Unavailable",
      "CustomFieldList": []
    },
    {
      "Id": 1252643,
      "Text": "<p>We've done something and now the application is just slow and not down!<br></p>",
      "Date": "2024-09-26T13:58:00",
      "IsPublished": true,
      "PostType": "Informational",
      "NewComponentStatus": "DegradedPerformance",
      "CustomFieldList": []
    },
    {
      "Id": 1252648,
      "Text": "<p>We've resolved something, lets turn that icon back to green.&nbsp;<br></p>",
      "Date": "2024-09-26T14:01:00",
      "IsPublished": true,
      "PostType": "Closed",
      "NewComponentStatus": "Available",
      "CustomFieldList": []
    }
  ],
  "AffectedComponents": [
    {
      "ComponentId": 436949,
      "ComponentName": "Communication channels",
      "IconImageSrc": "https://statuscastsaprdeast.blob.core.windows.net/pages/21225/001ba6fc4474487bb4390b53c9c3fcfa",
      "DirectlyEffected": false
    },
    {
      "ComponentId": 436953,
      "ComponentName": "Chat",
      "DirectlyEffected": true
    },
    {
      "ComponentId": 436952,
      "ComponentName": "Email",
      "DirectlyEffected": true
    }
  ],
  "CustomFieldList": []
}

Webhook Elements List

Here is a list of the elements and arrays that are included in the webhook:

Elements

Element	Definition	Format	Example
Id	Incident identifier	Numeric	417149
DateCreated	Date the event was created in StatusCast(not the start date of the event)	yy-mm-ddThh:mm:ss	2023-03-21T20:34:11.18
IncidentType	The type of event that was created; Incident, Informational, or Maintenance	String	"ScheduledMaintenance" "ServiceUnavailable" "Informational"
Status	Status of the incident.	String	"InProgress" "Closed" "Future"
Title	The title or subject of the incident.	String	"Performance Degradation Notification"
AutoGeneratedId	The custom ID if using custom incident IDs. Null if feature is disabled	Numeric
StartDate	The date the incident started.	yy-mm-ddThh:mm:ss	"2022-02-16T16:27:28"
EndDate	The date the incident ended. Value may be NULL if incident is ongoing.	yy-mm-ddThh:mm:ss	"2022-02-17T16:27:28"
ShortUrl	A shortened URL pointing to the incident details page of the event in question.	String
ExternalId	The external identifier of the incident. Used by default when beacons generate incidents from outside resources.	Numeric	756326
EstimatedDurationMinutes	The entered value for estimated time if the event is a maintenance. Will be NULL for non-maintenance events.	Numeric	30
CustomFieldList	List of the custom fields included in the incident. Value may be NULL if incident is ongoing or if custom field values have not been entered.	Array
Groups	A list of impacted group names if subscriber has access. May be NULL if no groups are used within an event or account.	Array	[ 131948, 132052]

Note: all these elements are included in every webhook, but not all my have data depending on the status of the incident.

CurrentComponentStatus/ PreviousComponentStatus - Array

Element	Description	Format	Example
ComponentId	ID of the service component	Numeric	456570
Status	Status of the component	String	"Unavailable" "DegradedPerformance" "Maintenance" "Informational" "Investigating" "Monitoring" "Identified"
DateChanged	Date the component status has changed	yy-mm-ddThh:mm:ss	"2023-03-21T20:54:45"

Posts - Array

Element	Description	Format	Example
ID	Update Post ID	number	896335
Text	Text of the post	String	"The API is degraded"
Date	Date of Post	yy-mm-ddThh:mm:ss	"2023-03-21T20:54:45"
IsPublished	State of Post	boolean	true;false
PostType	Incident State during Post	String	"Informational" "Investigating" "Monitoring" "Identified" "RootCause" "Closed"
NewComponentStatus	State of the Service Component	String	"Unavailable" "DegradedPerformance" "Maintenance" "Informational" "Investigating" "Monitoring" "Identified" "Available"
CustomFieldList	Custom Tags	String

Affected Components - Array

Element	Description	Format	Example
ComponentId	ID of the service component	Numeric	456570
ComponentName	Name of Component	String	"Test Server"
IconImageSrc	URL of image	String	"https://statuscastsaprdeast.blob.core.windows.net/pages/21300"
DirectlyEffected	How the component has been affected	boolean	true;false

Webhook Signatures

As an added method of security StatusCast can add a signatures to the header of webhook notifications. This is only available in the Settings > Integrations > Webhook feature and is not accessible to subscribers who subscribed via webhook. To enable this integration click Install on the Webhook card.

Enter your Webhook URL endpoint and select the Use Signature Header box. Your integration will include a Public Key and Private Key. StatusCast follows the HMAC authentication workflow by adding the following header pattern:

"X-StatusCast-Signature" Header in format "{PublicKey}:{Signature}:{Nonce}:{timestamp}"

Using SHA256 your server will need to extract the values (Public Key, Signature, Nonce and Request Time stamp) from the Authorization header to validate its authenticity.

Troubleshooting Webhooks

What you do with a webhook can be varied, whether you are using an application like Slack or have some custom code expecting a payload -- when it goes wrong what can you do?

Contact the organization who maintains the status page. StatusCast has detailed logs on if we were able to successfully send the request to your end point, and an account administrator can verify this for you.*
Check if your endpoint expects a certain format. As mentioned above Slack and MS Teams expect a specific JSON format in order to integrate properly. StatusCast sends its own JSON object in all other cases, so check if your endpoint has any format requirements.
Check your endpoint's logs and/or enable them. If your endpoint takes the JSON response and runs it through custom code to execute another action, you should enable logging to help troubleshoot failures once the webhook has been successfully sent.