# Incident Webhook (Incident Webhook/API)

This document will help you configure Incident Webhook to route alerts from monitoring tools or your internal (bespoke) systems into Squadcast. Incident Webhook can do both, trigger and resolve incidents in Squadcast, through HTTP POST requests.

Route detailed monitoring alerts coming in via Incident Webhook to the right users in Squadcast.

{% hint style="info" %}
**Note:**

We also support outgoing webhooks. You can find detailed information on how to configure them [<mark style="color:blue;">here</mark>](https://support.squadcast.com/integrations/outgoing-webhooks).
{% endhint %}

## How to configure Incident Webhook <a href="#how-to-configure-incident-webhook" id="how-to-configure-incident-webhook"></a>

### In Squadcast: Using Incident Webhook as an Alert Source <a href="#in-squadcast-using-incident-webhook-as-an-alert-source" id="in-squadcast-using-incident-webhook-as-an-alert-source"></a>

1. From the navigation bar on the left, select **Services**. Pick the applicable **Team** from the Team-picker on the top. Next, click on **Alert Sources** for the applicable Service

<figure><img src="https://1574591692-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F8TaWz01jmUJl58p4ZVel%2Fuploads%2Fgit-blob-cda844024ab35a1d8dddf6c4a628ebeb6da8aef9%2Falert_source_1.png?alt=media&#x26;token=e0a3b3a9-9a24-41ac-9bfd-397b61a56de5" alt="configuration Incident Webhook as an Alert Source" width="563"><figcaption></figcaption></figure>

2. Search for **Incident Webhook** from the Alert Source drop-down and copy the Webhook URL. Use this Webhook URL endpoint to send <mark style="color:red;">`HTTP POST`</mark> requests

![Selection of Incident Webhook from the Alert Source](https://1574591692-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F8TaWz01jmUJl58p4ZVel%2Fuploads%2Fgit-blob-c567ef5db1ff5b0806b81998f40e416f5e38119d%2Fapiv2_1.png?alt=media)

{% hint style="warning" %} <mark style="color:orange;">**Important**</mark>**:**

For an Alert Source to turn active (indicated by a **green dot - Receiving alerts** against the name of the Alert Source in the drop-down), you can either generate a test alert or wait for a real-time alert to be generated by the Alert Source.

An Alert Source is active if there is a recorded incident via that Alert Source for the Service in the last 30 days.
{% endhint %}

{% hint style="info" %} <mark style="color:blue;">**Add header before making POST request**</mark>

Ensure that you add a header <mark style="color:red;">`Content-Type`</mark> with value `application/json` while making the <mark style="color:red;">HTTP POST</mark> request
{% endhint %}

The body of the POST request should contain the details of your incident in the following format:

```
{
  "message": "This will be the incident message",
  "description": "This will be the incident description",
  "tags" : {
    "tagname1":"Tag value#1",
     "tagname2":"Tag value#2",
     "tagname3": {
       "color": "Valid HTML HEX Colour Notation goes here",
       "value":"Tag value#3"
     }
  },
  "priority": "P5",
  "status": "trigger",
  "event_id": "6"
}
```

{% hint style="info" %} <mark style="color:blue;">**Mandatory fields within the JSON**</mark>

Kindly note that the **message** and **description** fields in the JSON are mandatory to trigger an incident in Squadcast. You can enrich your incidents by adding other details optionally, in the same format as seen above in the example JSON
{% endhint %}

{% hint style="warning" %} <mark style="color:orange;">**Important**</mark><mark style="color:orange;">:</mark>

* By default, incidents are triggered with an initial status. However, to resolve an incident, you must explicitly send a status update indicating that it has been resolved.
* Moreover, each incident requires a unique Event ID to be entered by the user. When resolving a specific incident, you must specify the corresponding unique Event ID. In the event of multiple incidents associated with the same Event ID, resolving one incident will result in the resolution of all incidents linked to that specific Event ID.
* If you do not provide an Event ID, any previous incidents without an Event ID will be automatically marked as resolved.
* The Event ID is an optional field and should not be confused with the Incident ID. They serve different purposes.
  {% endhint %}

{% hint style="info" %} <mark style="color:blue;">**Note:**</mark>

1. Allowed values for priority are `P1`, `P2`, `P3`, `P4`, and `P5`.
2. If a value other than the allowed ones or no value is passed, Squadcast will have the priority level as `Unset`. Users can manually edit the priority via the web or the mobile app.
   {% endhint %}

{% hint style="info" %}
🔹 **Best Practice Tip** 🔹 While the Event ID is not mandatory, we strongly recommend including it to prevent the automatic resolution of triggered incidents without an Event ID. Adding the Event ID ensures that all incidents without an assigned Event ID are not auto-resolved.
{% endhint %}

{% hint style="danger" %} <mark style="color:red;">**Payload Size Limitation**</mark>\
The payload size is limited to 30KB. Any payload that crosses this limit will not be processed.\
You will receive \[HTTP Status Code 413]\(<https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/413>) to notify you of this.
{% endhint %}

### Event Identification and Resolution <a href="#event-identification-and-resolution" id="event-identification-and-resolution"></a>

This section will give you an understanding of how one can associate alerts with Squadcast incidents and resolve them with an API call.

#### Typical Incident JSON <a href="#typical-incident-json" id="typical-incident-json"></a>

```
{
  "message": "This will be the incident message",
  "description": "This will be the incident description",
  "status": "trigger",
  "event_id": "6"
}
```

This triggers an incident and associates the incident with the <mark style="color:red;">`event_id`</mark> value as specified. This <mark style="color:red;">`event_id`</mark> can be used to resolve the above-created incident with an API call.

To resolve an incident, a JSON with the format shown below should be sent.

```
{
  "status": "resolve",
  "event_id": "6"
}
```

* The <mark style="color:red;">`status`</mark> field should be set to the value <mark style="color:red;">`"resolve"`</mark>
* The associated <mark style="color:red;">`event_id`</mark> should also be sent along with this

{% hint style="info" %} <mark style="color:blue;">**Resolving an Incident with an API call**</mark>**:**

To resolve an incident, **message** and **description** fields are not required to be sent.
{% endhint %}

### Add a Tag From directly Incident JSON <a href="#add-a-tag-from-directly-incident-json" id="add-a-tag-from-directly-incident-json"></a>

This section will give you an understanding of how you can add tags to an incident straight from the Incident JSON using the Incident Webhook.

#### Typical Incident JSON: <a href="#typical-incident-json-1" id="typical-incident-json-1"></a>

```
{
   "message":"This will be the incident message",
   "description": "This will be the incident description",
   "tags": {
     "tagname1":"Tag value#1",
     "tagname2":"Tag value#2",
     "tagname3": {
       "color": "Valid HTML HEX Colour Notation goes here",
       "value":"Tag value#3"
     }
   }
}
```

#### Example 1: Using `tags` to set the *Severity* for the incident <a href="#example-1-using-tags-to-set-severity-for-the-incident" id="example-1-using-tags-to-set-severity-for-the-incident"></a>

```
{
  	"message": "Error rates higher than usual",
    "description": "HTTP Error rates for srv_90 is above 90 counts/hour",
    "tags": {
    	"severity": "high"
    }
}
```

{% hint style="info" %} <mark style="color:blue;">**The default colour for Tags**</mark>**:**

If a color code is not mentioned explicitly, then the system takes the default color "**#808080**" (gray) for tags
{% endhint %}

To specify a color explicitly for `tags`:

```
{
	"message": "Error rates higher than usual",
  "description": "HTTP Error rates for srv_90 is above 90 counts/hour",
	"severity": {
  	"colour": "#FF0000",
  	"value":"backend"
  }
}
```

#### Example 2: Adding different tags to an incident <a href="#example-2-adding-different-tags-to-an-incident" id="example-2-adding-different-tags-to-an-incident"></a>

```
{
	"message": "Error rates higher than usual",
  "description": "HTTP Error rates for srv_90 is above 90 counts/hour",
	"tags" : {
   	"priority": "P1",
	  "impact_level": 5,
   	"classification": {
    	"color":"#FF0000",
     	"value":"backend"
     }
 	}
 }
```

*Have any questions?* [*Ask the community*](https://community.squadcast.com/view/home)*.*