Adding a custom webhook destination

When configuring notifications in SquaredUp, you can specify a custom webhook to be used as a notification destination.

While configuring a custom webhook is more complex than the other available destination options it is also powerful, allowing you to send a notification to any HTTP POST endpoint.

For example, you can use a third-party service like https://apify.com/ to send a customized email.

Configuring a custom webhook

The JSON body of the webhook request is customizable, using inserts to specify elements of the notification – including the name of the monitored entity (e.g. SquaredUp Workspace name), the previous and new states, and a link back to the SquaredUp app.

This is an example of the JSON body:

{
  "text": "{{stateSymbol}} {{name}} changed from {{oldState}} to {{newState}}.",
  "link": "{{link}}"
}

{
  "subject": "{{stateSymbol}} {{name}} has changed from {{oldState}} to {{newState}}.",
  "html": "Hi there t<p>{{stateSymbol}} The health of <b><a href='{{link}}'>{{name}}</a></b> has changed from <b>{{oldState}}</b> to <b>{{newState}}</b>.<p style='color:blue;font-size:0.9em''><em>Brought to you by SquaredUp Alerts™</em>",
  "to": "[email protected]"
}

Custom Notifications Guide

A custom notification destination consists of a URL and a template for the message body that is POST-ed to the URL.

A web site like https://webhook.site can be used to experiment with custom notifications before integrating with your destination.

Supported webhooks

The webhook must take a JSON body passed via POST. It is not possible to pass headers. Authentication is not supported. The URL can include query parameters but they must be fixed - the URL cannot contain variables like the body.

Template structure

The body of the notification must be specified as a template. The template specifies the structure of the JSON passed to the webhook, along with variables that are replaced with details of the notification when each notification is sent.

A simple webhook body structure is

{
	"text": "{{stateSymbol}} {{name}} changed from {{oldState}} to {{newState}}."
}

The JSON is an object with a single text property. This structure works for many destinations - Slack, Teams, Google Chat etc. However, often more advanced structures can be used to give more options and more sophisticated formatting. Consult the documentation for the destination system to discover all of the options. A web search for incoming webhook and your destination type may prove useful.

Template variables

Template variables use the Mustache syntax. The following parameters are available.

Template variable tips

Normal text variables should use double-curly-brackets, e.g. {{name}}.

URLs should use triple-curly-brackets to avoid being broken by escaping, e.g. {{{link}}}.

Some variables are not populated for all notification types. To make a section of the template conditional on a variable having a value, use a conditional block, e.g. {{#var1}} This is only included if var1 has a value{{/var1}}.

Examples

Plain text

A simple notification that supports all notification types but does not include any details for tile monitor notifications. This will work with many destination types including Slack, Teams and Google Chat.

{
	"text": "{{stateSymbol}} {{name}} changed from {{oldState}} to {{newState}}. View in SquaredUp: {{{link}}}"
}

This will work with many destination types including Slack, Teams and Google Chat.

{
	"text": "{{stateSymbol}} {{name}} changed from {{oldState}} to {{newState}}. {{#stateReason}}{{stateReason}}. {{/stateReason}}{{#imagePreviewUrl}}Tile preview: {{imagePreviewUrl}}. {{/imagePreviewUrl}}View in SquaredUp: {{{link}}}. Change your notification preferences: {{{notificationsConfigLink}}}"
}

Rich formatting using Slack ‘blocks’:

This will only work with Slack.

{
	"blocks": [
		{
			"type": "section",
			"text": {
				"type": "mrkdwn",
				"text": "{{stateSymbol}} *<{{{link}}}|{{name}}>* changed from {{oldState}} to *{{newState}}*.{{#stateReason}}\n {{stateReason}}.{{/stateReason}}{{#tileName}}\nThis monitor is part of the <{{{dashboardLink}}}|*{{dashboardName}}*> dashboard in the <{{{workspaceLink}}}|*{{workspaceName}}*> workspace.{{/tileName}}{{#imagePreviewUrl}}\nTile preview <{{imagePreviewUrl}}|here>.{{/imagePreviewUrl}}\nChange your notification preferences <{{{notificationsConfigLink}}}|here>."
			}
		}
	]
}

Rich formatting using Teams ‘MessageCard’

This will only work with MS Teams.

{
	"@context": "https://schema.org/extensions",
	"@type": "MessageCard",
	"themeColor": "5D3FD3",
	"text": "{{stateSymbol}} [**{{name}}**]({{&link}}) changed from {{oldState}} to **{{newState}}**.",
	"sections": [
		{
			"text": "{{#stateReason}}{{stateReason}}. {{/stateReason}}{{#tileName}}This monitor is configured on the [**{{dashboardName}}**]({{&dashboardLink}}) dashboard in the [**{{workspaceName}}**]({{&workspaceLink}}) workspace.{{#imagePreviewUrl}}![Tile preview]({{&imagePreviewUrl}}){{/imagePreviewUrl}}{{/tileName}}",
			"potentialAction": [
				{
					"@type": "OpenUri",
					"name": "View",
					"targets": [
						{ "os": "default", "uri": "{{{link}}}" }
					]
				}
			]
		},
		{
			"text": "Change your notification preferences [**here**]({{{notificationsConfigLink}}})."
		}
	]
}

Adding a destination in SquaredUp

1. A new destination can be configured when adding a notification rule in the Monitors section inside a workspace, or under Settings > Notifications

2. Destination Name:
   Enter a name for your destination. This helps you to identify this destination in the list of your destinations.

3. URL:
   Paste the webhook URL to configure the destination in SquaredUp.

4. Body:
   Enter the JSON body for the channel.

5. Test:
   Click to send a test notification and check that it is working as expected.

Was this article helpful?