...

Webhooks: When there’s a business service that needs to ingest information about an Apica monitoring check (status, alert, message), the Webhook, as a push service, is a passive way to receive this information. So, a set of alert integration placeholders has been defined and customized to your service needs.

Message Placeholders

...

A placeholder has the following format:

%placeholder-name%

There is a set of predefined placeholders configured in ASM:

...

Check-related Placeholders

Webhook Placeholders

Default placeholders are surrounded by a pound/hashtag # character.

A default set of placeholders has been provided. These can be configured with the Webhook alert integration, or you may customize your Webhook placeholders as necessary.

...

The default placeholders above should only be considered suggestions. It is also possible to define your own webhook placeholders, which will pull their value from some response content which comes back from an API call. These custom-defined placeholders are also surrounded by a pound/hashtag # character.

Consider the following example:

...

Essentially, in the above example, when the GET request is resolved, the value of #url# becomes whatever is found in the “url” property of the response body. In the above example, the recipient of the check will instantly know that the check goes to https://www.msn.com.

Alert Configuration Examples

The following examples explain various advanced configurations. For explicit instructions on how to set up the Webhook configurations shown below, refer to the article Configuring Webhook Alerts.

API keys/dynamic tokens/etc. are always generated on the recipient alerting platform side. For instructions on how to generate these tokens, refer to the alerting platform’s API documentation.

E-mail

...

Custom Message:

The status changed to %SEV% from %OLD_SEV_WORD% %TT% (%UTC% UTC) for check "%CHECK_NAME%" (id %CHECK_ID%   from  %LOCATION%  ).

Message:

%M%

The check is run from %LOCATION%.

http://wpm.apicasystem.com/check/details/%CHECK_ID%

The above E-mail message uses placeholders. See

OpsGenie

...

Host: https://api.opsgenie.com

API key: generated on the OpsGenie side

Message: %CHECK_NAME% Status Has Changed

Alias: %CHECK_NAME%

Description: a custom description for the alert which gives identifying information about the Alert.

Here is an example Description (some identifying information removed):

The status changed to *Error* (from Info) at *2022-07-05 14:54:39 (GMT-04:00)* for the check <https://wpm.apicasystem.com/BrowserResult/Details?checkId={checkId}&resultId={resultId}> Message: *Fullpage (FF) check 'test waitForText' failed [Error on 4 URL(s) Time (8272) was above upper limit (2000 ms)]* The check is run from *Check Location*.

Slack

URL: generated on the Slack side

...

Custom Webhook w/ message placeholder (Microsoft Teams)

For instructions on setting up the URL which will be used as both the “Trigger URL” and the “Resolution URL”, refer to the official Microsoft documentation here.

...

Data: For both the trigger and resolution request sequences, the placeholder %CHECK_ID% is used along with a custom message to inform the user that the alert has been triggered/resolved.

Example alert trigger/resolution within a configured Microsoft Teams channel:

...

Custom Webhook w/ message placeholder (OpsGenie)

...

Trigger URL: https://api.opsgenie.com/v2/alerts?apiKey={opsGenieApiKey} (opsGenieApiKey is generated on the OpsGenie end)

Data:

{
   "message":"%CHECK_NAME%",
   "alias":"%CHECK_ID%",
   "description":"%CHECK_DESCRIPTION%",
   "responders":[
      {
         "name":"SAT",
         "type":"team"
      }
   ],
   "visibleTo":[
      {
         "name":"SAT",
         "type":"team"
      }
   ],
   "priority":"P1",
   "user":"ASM"
}

This JSON data is an example which we’ve created based on your current OpsGenie integration. The payload can be customized by referring to this documentation: https://docs.opsgenie.com/docs/alert-api#create-alert

%CHECK_NAME%, %CHECK_ID%, and %CHECK_DESCRIPTION% are message placeholders. Alias must be %CHECK_ID% in order for the resolution request to function correctly.

Resolve URL: https://api.opsgenie.com/v2/alerts/%CHECK_ID%/close?identifierType=alias&apiKey={opsGenieApiKey} (opsGenieApiKey is generated on the OpsGenie end)

%CHECK_ID% is a string which dynamically grabs the check ID of the check, which has ALSO been set as the Alias of the alert. It is possible to close Alerts via alert Alias, which we defined to be the Check ID in the Trigger Sequence request body. Thus, by specifying the Check ID as both the alias of the alert, we are able to dynamically identify and close the alert we created before. “identifierType=alias” is required.

Data (resolution request):

{“user”:”ASM”}

The response body of the resolution alert cannot be empty. Thus, at least one property must be present in the JSON body, although the POST call does not require any data from the OpsGenie end. It is possible to add a resolution note as well; see https://docs.opsgenie.com/docs/alert-api#close-alert for more details concerning closing alerts.

Custom Webhook w/ message placeholder, a custom placeholder (Slack)

...

Response Parameters: although the UI asks for the XPath for finding XML, it is also capable of finding JSON properties with the XPath. In this instance, we want to capture the value of the URL property of the HTTP response of our Sub Request (the api-wpm.apicasystem.com request).

As such, we will use #url# to display the “url” property of the api-wpm API call in our resolution message.

Trigger Request: the initial API call we make when the Alert is Triggered. Generated from the Slack end. Example: https://hooks.slack.com/services/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

Data: Note that the data contains a Message Placeholder, %CHECK_NAME%, which allows us to display dynamic data in the Slack message body.

Severity: We can have different Payload data (that is, different request messages) for different severities if we so desire. That is not needed for our use case, so we will use one payload for Warning, Error, and Fatal.

Sub Requests: After the initial request to https://hooks.slack.com is made, we want to get ADDITIONAL information about the check from an API call which gives us more check data. We store that data in the Response Parameter we explained above. Example: https://api-wpm.apicasystem.com/v3/checks/{check_id}?auth_ticket={auth_ticket}

Resolution Request: the final API call we make when the Alert is Resolved. Note the usage of both Message and Webhook placeholders to give our resolution message that dynamic data we need. Generated from the Slack end. Example: https://hooks.slack.com/services/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

Here are examples of the request/resolution messages that are sent to Slack based on the above configuration:

...