# Outgoing Webhooks

Webhooks allow you to connect a platform you manage (either an API you create by yourself or a third-party service) to a stream of future events.

Setting up a Webhook on Squadcast enables you to receive information (referred to as events) from Squadcast as they happen. This can help you avoid continuously polling Squadcast’s REST APIs or manually checking the Squadcast web/mobile application for desired information.

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

We also support *generic incoming Webhooks* for incident creation. You can find detailed information on how to use those [<mark style="color:blue;">here</mark>](https://support.squadcast.com/integrations/incident-webhook-incident-webhook-api)<mark style="color:blue;">.</mark>
{% endhint %}

### Prerequisites <a href="#prerequisites" id="prerequisites"></a>

Only the **Account Owner** and **Users** with the <mark style="color:red;">`Manage Webhook`</mark> permission will be able to *enable*, *disable* and *manage* Webhooks in Squadcast.

If you do not have access to this feature, please contact your account admin to give you the right permissions.

Navigate to **Settings** -> **Permissions** and enable the checkbox under **Webhooks** for the desired users.

<figure><img src="https://1574591692-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F8TaWz01jmUJl58p4ZVel%2Fuploads%2Fgit-blob-1f9b3f5a8563088d3a605a11467084aa6006c75b%2FWebhooks_gb_1.png?alt=media" alt="Setting up Webhooks permission"><figcaption><p>Setting up Webhooks permission</p></figcaption></figure>

### **Add Webhooks** <a href="#setup-a-webhook" id="setup-a-webhook"></a>

To add a Webhook,

1. Navigate to **Settings** -> **Webhooks**
2. Click **Add Webhook**. On the next screen, you will be guided through three steps. Navigate between these steps by clicking on any of the steps on the top bar.
3. **Add Webhook Details**:

   <figure><img src="https://1574591692-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F8TaWz01jmUJl58p4ZVel%2Fuploads%2Fgit-blob-f7ea605c007c0d88ed584c0ea080b265b5802868%2FWebhooks_gb_2.png?alt=media" alt="Step 1: Add Webhook Details"><figcaption><p>Step 1: Add Webhook Details</p></figcaption></figure>

   1. **Webhook Name**: Enter the **Webhook Name**.
   2. **Webhook Description** (*optional*): Enter an optional **description**.
   3. **Failure Notification Email** (*optional*): Enter an email where you want to receive failure notifications. This is particularly helpful when you (or an administrator) would want to be notified of Webhook-related failures.
   4. **URL**: Enter the **Webhook URL**. We support the addition of multiple URL endpoints, with <mark style="color:red;">POST</mark>, <mark style="color:red;">PUT</mark>, and <mark style="color:red;">PATCH</mark> methods. Incident payloads will be sent to all the URL endpoints that are added.
   5. **Additional Headers** (*optional*): You can also configure additional headers. These headers will get attached to all the Webhook calls that will be made based on this configuration. **Note**: Content-Type: application/JSON is added by default.

   Click **Save Changes**, and navigate to the next step.
4. **Choose Webhook Type**: Choose Webhook type (Manual or Automatic) and add configurations.

   <div><figure><img src="https://1574591692-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F8TaWz01jmUJl58p4ZVel%2Fuploads%2Fgit-blob-c75dc8b3e8d8e066ff420537b2349875942af48e%2FWebhooks_gb_3.png?alt=media" alt="Step 2(a): Configure Manual Webhook"><figcaption><p>Step 2(a): Configure Manual Webhook</p></figcaption></figure> <figure><img src="https://1574591692-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F8TaWz01jmUJl58p4ZVel%2Fuploads%2Fgit-blob-d1ef0c8b0a308ef52b1c693e5205e4cdd47593e7%2FWebhooks_gb_4.png?alt=media" alt="Step 2(b): Configure Automatic Webhook"><figcaption><p>Step 2(b): Configure Automatic Webhook</p></figcaption></figure></div>

   1. **Manual Webhook**: Manually trigger Webhooks under incidents, on demand. Under Manual Webhook, select the teams that are authorized to access the Webhook. You can select All Teams or enter specific Teams, from the drop-down.
   2. **Automatic Webhook**: Automatically trigger Webhooks when the configured conditions match. To set up Automatic Webhook Configurations:

      1. **Versions**: Select the version from the drop-down.
         1. V1 supports limited events which are backward compatible
         2. V2 is the latest version and supports a lot more events
      2. **Triggers**: Select the Trigger events (conditions) for which the Webhook will be triggered.
      3. **Filters**: You can apply filters on top of events, based on Teams, Services, Alert Sources, Priorities, and Tags, either by having an individual expression or a combination of expressions/expression groups.

         Applying filters will allow the Webhook to be triggered only for events that match the filter.

      Click **Next: Configure Payload**, and navigate to the next step.
5. **Configure Payload**: Configure the payload based on your selected Webhook type.

   <div><figure><img src="https://1574591692-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F8TaWz01jmUJl58p4ZVel%2Fuploads%2Fgit-blob-05c589c5dd9980079c0c1dc515d1945eb4ba3be4%2FWebhooks_gb_5.png?alt=media" alt="Step 3(a): Configure payload for Manual Webhook"><figcaption><p>Step 3(a): Configure payload for Manual Webhook</p></figcaption></figure> <figure><img src="https://1574591692-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F8TaWz01jmUJl58p4ZVel%2Fuploads%2Fgit-blob-ad966df01036111a33e7c72baaee4d35c0c5a228%2FWebhooks_gb_6.png?alt=media" alt="Step 3(b): Configure payload for Automatic Webhook"><figcaption><p>Step 3(b): Configure payload for Automatic Webhook</p></figcaption></figure></div>

   1. **Manual Webhook:**
      1. **Payload Templates**: Select one of the pre-configured templates, or create your own payload. If you want to add more commonly used templates, create a PR on [<mark style="color:blue;">GitHub</mark>](https://github.com/SquadcastHub/squadcast-webhook-templates)<mark style="color:blue;">.</mark>
      2. **Payload**: You can reference your selected template payload here. You can modify the payload and validate it before saving the Webhook. You can also test the Webhook by clicking on the Test Webhook on the bottom right.
   2. **Automatic Webhook**: You can select between the standard Squadcast payload for all trigger events or customize the payload based on the pre-configured templates.
      1. **Standard Squadcast Payload**: You will find the standard payload for your selected trigger events based on the version you have selected. **Note**: You can only test the Webhook for the first trigger event you have selected in Step 2.
      2. **Custom Payload**: You can reference your selected template payload here. You can modify the payload and validate it before saving the Webhook. You can also test the Webhook by clicking on the Test Webhook on the bottom right. **Note**: You can only test the Webhook for the first trigger event you have selected in Step 2.

Click **Save** and you're done.

{% hint style="warning" %}
**Important:**

Squadcast uses the below IPs from which it sends Webhook requests. You may need to whitelist these IPs with your firewall to use Webhooks without any issues.

For US region: 34.148.46.58

For EU region: 35.246.154.28
{% endhint %}

### Supported Events <a href="#supported-events" id="supported-events"></a>

The Webhooks that you have configured can be triggered for certain Trigger Events occurring in Squadcast.

You can choose multiple Trigger Events for a Webhook. Information is sent to the provided URLs if any of the triggers match. The following event types are available for each Webhook version:

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

Payloads for event types part of both versions are different for each.
{% endhint %}

<table><thead><tr><th>Resource</th><th>Event</th><th width="172">v1</th><th>v2</th></tr></thead><tbody><tr><td>Incident</td><td>triggered</td><td>✔️</td><td>✔️</td></tr><tr><td></td><td>reassigned</td><td>✔️</td><td>✔️</td></tr><tr><td></td><td>acknowledged</td><td>✔️</td><td>✔️</td></tr><tr><td></td><td>resolved</td><td>✔️</td><td>✔️</td></tr><tr><td>Communication Channel</td><td>created</td><td></td><td>✔️</td></tr><tr><td></td><td>updated</td><td></td><td>✔️</td></tr><tr><td></td><td>deleted</td><td></td><td>✔️</td></tr><tr><td>Incident Notes</td><td>created</td><td></td><td>✔️</td></tr><tr><td></td><td>updated</td><td></td><td>✔️</td></tr><tr><td></td><td>deleted</td><td></td><td>✔️</td></tr><tr><td></td><td>starred</td><td></td><td>✔️</td></tr><tr><td></td><td>unstarred</td><td></td><td>✔️</td></tr><tr><td>Incident Tags</td><td>updated</td><td></td><td>✔️</td></tr><tr><td>Incident Task</td><td>created</td><td></td><td>✔️</td></tr><tr><td></td><td>updated</td><td></td><td>✔️</td></tr><tr><td></td><td>deleted</td><td></td><td>✔️</td></tr><tr><td></td><td>completed</td><td></td><td>✔️</td></tr><tr><td></td><td>uncompleted</td><td></td><td>✔️</td></tr><tr><td>Postmortem</td><td>created</td><td></td><td>✔️</td></tr><tr><td></td><td>updated</td><td></td><td>✔️</td></tr><tr><td></td><td>deleted</td><td></td><td>✔️</td></tr><tr><td>SLO-Violating Incident</td><td>created</td><td></td><td>✔️</td></tr><tr><td></td><td>marked false positive</td><td></td><td>✔️</td></tr><tr><td></td><td>unmarked false positive</td><td></td><td>✔️</td></tr><tr><td></td><td>spent error budget</td><td></td><td>✔️</td></tr><tr><td>StatusPage</td><td>updated</td><td></td><td>✔️</td></tr></tbody></table>

{% hint style="info" %}
**Note**: Additional event types may be added to this list over time.
{% endhint %}

{% hint style="info" %}
**Note**: If your use case requires more Squadcast events to be supported, please contact our [<mark style="color:blue;">Support team</mark>](mailto:support@squadcast.com) with the details for the same.
{% endhint %}

### **Edit Webhooks**

To edit the Webhook configurations,

Navigate to **Settings** -> **Webhooks** -> Hover over any Webhook you want to edit and click **Edit Webhook**. It will open up to the guided three-step creation flow, where you can edit by navigating between these steps by clicking on any of the steps on the top bar.

<figure><img src="https://1574591692-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F8TaWz01jmUJl58p4ZVel%2Fuploads%2Fgit-blob-6ea7984bfd671e3cfa96fb0648795aa179ada740%2FWebhooks_gb_7.png?alt=media" alt="Steps to edit a Webhook"><figcaption><p>Steps to edit a Webhook</p></figcaption></figure>

### **Delete Webhooks**

To delete a Webhook,

Navigate to **Settings** -> **Webhooks** -> Under more options, click **Delete**. You will receive a confirmation dialog prompt to confirm the deletion, click **Delete**.

<figure><img src="https://1574591692-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F8TaWz01jmUJl58p4ZVel%2Fuploads%2Fgit-blob-f8f93587bbb39f5c251a81dd48a23ece58b30c58%2FWebhooks_gb_8.png?alt=media" alt="Steps to delete a Webhook"><figcaption><p>Steps to delete a Webhook</p></figcaption></figure>

### Communication Protocol for Webhooks <a href="#communication-protocol-for-webhooks" id="communication-protocol-for-webhooks"></a>

A Webhook is called whenever the configured events occur in Squadcast.

A Webhook call is made using the <mark style="color:red;">`HTTP POST`</mark> method to the URL(s) that were added when the Webhook was configured, with a body that is encoded using <mark style="color:red;">`JSON`</mark>.

Squadcast expects the server that responds to the webhook to return a 2xx response code upon success. If a non-2xx response is received, **Squadcast will retry the request a maximum of 3 times**, over a period of time.

### **View Logs**

To view logs for Webhook calls that have been made,

Navigate to **Settings** -> **Webhooks** -> Hover over any Webhook you want to view the logs for and click **View Logs**. You can view the Timestamp, Status, and Payloads for each Webhook call.

<figure><img src="https://1574591692-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F8TaWz01jmUJl58p4ZVel%2Fuploads%2Fgit-blob-2f628b9cf04ef1caeb6a9bc0691c55bcf3e66f59%2FWebhooks_gb_9.png?alt=media" alt="Steps to view logs for Webhook calls"><figcaption><p>Steps to view logs for Webhook calls</p></figcaption></figure>

### **Use Cases for Webhooks**

Webhooks can be leveraged in various scenarios. We have put together some common use cases.

They are:

* Building internal custom dashboards to visualize or analyze incidents
* Sending data to ticketing tools like Zendesk, Freshdesk, Shortcut, Asana, etc.
* Sending events to communication apps like Slack, MS Teams, etc.
* Alerting when a workflow is disrupted- then using the API to re-run the workflow
* Triggering internal notification systems to alert people when incidents are created/resolved
* Building your own automation plug-ins and tools

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

Please contact our [<mark style="color:blue;">Support team</mark>](mailto:support@squadcast.com) if you need help integrating your Squadcast account into a third-party application using Webhooks.
{% endhint %}

### Sample Webhook Payloads

To see the sample Webhook payloads, click [<mark style="color:blue;">here</mark>](https://developer.squadcast.com/outgoing-webhooks/payload/)<mark style="color:blue;">.</mark>

### Limitations of Webhooks

1. The Webhooks API provides "at least once" delivery of Webhook events. This means that an endpoint might receive the same Webhook event more than once. You should be able to handle any possible duplicates.
2. Ordering amongst Webhooks isn't guaranteed between different topics for the same resource. For example, it's possible that an incident-triggered Webhook for a second incident might get triggered before the first incident when there are many incidents created in quick succession.
3. Webhook delivery isn't always guaranteed. You should therefore implement reconciliation jobs to fetch data from Squadcast periodically.

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://support.squadcast.com/integrations/outgoing-webhooks.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.