Outgoing Webhooks
Use outbound webhooks to send incident information from Squadcast into other systems
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.
Note:
We also support generic incoming Webhooks for incident creation. You can find detailed information on how to use those here.
Prerequisites
Only the Account Owner and Users with the Manage Webhook 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.
Add Webhooks
To add a Webhook,
Navigate to Settings -> Webhooks
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.
Add Webhook Details:
Webhook Name: Enter the Webhook Name.
Webhook Description (optional): Enter an optional description.
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.
URL: Enter the Webhook URL. We support the addition of multiple URL endpoints, with POST, PUT, and PATCH methods. Incident payloads will be sent to all the URL endpoints that are added.
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.
Choose Webhook Type: Choose Webhook type (Manual or Automatic) and add configurations.
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.
Automatic Webhook: Automatically trigger Webhooks when the configured conditions match. To set up Automatic Webhook Configurations:
Versions: Select the version from the drop-down.
V1 supports limited events which are backward compatible
V2 is the latest version and supports a lot more events
Triggers: Select the Trigger events (conditions) for which the Webhook will be triggered.
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.
Configure Payload: Configure the payload based on your selected Webhook type.
Manual Webhook:
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 GitHub.
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.
Automatic Webhook: You can select between the standard Squadcast payload for all trigger events or customize the payload based on the pre-configured templates.
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.
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.
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
Supported Events
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:
Note:
Payloads for event types part of both versions are different for each.
| Resource | Event | v1 | v2 |
|---|---|---|---|
Incident | triggered | ✔️ | ✔️ |
reassigned | ✔️ | ✔️ | |
acknowledged | ✔️ | ✔️ | |
resolved | ✔️ | ✔️ | |
Communication Channel | created | ✔️ | |
updated | ✔️ | ||
deleted | ✔️ | ||
Incident Notes | created | ✔️ | |
updated | ✔️ | ||
deleted | ✔️ | ||
starred | ✔️ | ||
unstarred | ✔️ | ||
Incident Tags | updated | ✔️ | |
Incident Task | created | ✔️ | |
updated | ✔️ | ||
deleted | ✔️ | ||
completed | ✔️ | ||
uncompleted | ✔️ | ||
Postmortem | created | ✔️ | |
updated | ✔️ | ||
deleted | ✔️ | ||
SLO-Violating Incident | created | ✔️ | |
marked false positive | ✔️ | ||
unmarked false positive | ✔️ | ||
spent error budget | ✔️ | ||
StatusPage | updated | ✔️ |
Note: Additional event types may be added to this list over time.
Note: If your use case requires more Squadcast events to be supported, please contact our Support team with the details for the same.
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.
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.
Communication Protocol for Webhooks
A Webhook is called whenever the configured events occur in Squadcast.
A Webhook call is made using the HTTP POST method to the URL(s) that were added when the Webhook was configured, with a body that is encoded using JSON.
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.
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
Note:
Please contact our Support team if you need help integrating your Squadcast account into a third-party application using Webhooks.
Sample Webhook Payloads
To see the sample Webhook payloads, click here.
Limitations of Webhooks
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.
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.
Webhook delivery isn't always guaranteed. You should therefore implement reconciliation jobs to fetch data from Squadcast periodically.
Have any questions? Ask the community.
Last updated
