1. Home
  2. Alert Behavior
  3. Escalation Webhooks

Escalation Webhooks

Webhooks are a way to specify callbacks from VictorOps to your own applications, and can be added to your teams’ escalation policies in order to receive incident details and process them however you wish. Some examples of how these could be used:

  • Automatically bounce a server process when there’s an incident related to it.
  • Integrate VictorOps incidents into your own service dashboard.
  • Keep a status page up-to-date with outages

Webhook content type: application/x-www-form-urlencoded

Getting Started

To get started, from the VictorOps timeline go to Integrations and select Webhooks.

You then will be prompted for a Name and URL for the Webhook.  Once submitted, an Auth Code will be generated.

Authenticating Webhook Requests

When you create a webhook, we generate a secure, random authentication token. POST requests are signed with this key, so you can verify the incoming request, to make sure that it actually came from VictorOps.

In order to authenticate that the POST requests are arriving to your application from VictorOps complete these steps:

  1. Create a string with the URL of the webhook, exactly how it appears in VictorOps; this includes trailing slashes etc…
  2. Sort the request’s POST variables alphabetically by key.
  3. Append each POST variable’s key and value to the URL string, with no delimiter.
  4. Hash the resulting string with HMAC-SHA1, using the webhook’s authentication key to generate a binary signature.
  5. Base64 encode the signature
  6. Compare the output with the key X-VictorOps-Signature in the request – if it matches, the request originated from VictorOps.

SSL Certificate Chain Verification

If your webhook uses a secure connection (i.e. the URL starts with “https://”), the receiving endpoint must use a valid SSL certificate signed by a recognized Certificate Authority.

This recommendation was implemented based on SSL Labs Best Practices.


Webhook Escalation Steps

When a webhook is part of a team’s escalation policy, your service will receive an HTTP POST request when the incident is escalated. The request will contain the following information:

POST Body:

  • Incident: the identifier of the incident in VictorOps.
  • Summary: a short description of the incident.
  • Message: a message about the incident.

HTTP Headers

  • X-Victorops-Signature: a signature based on the auth key of the webhook in VictorOps

Once there is a webhook, it can be added to an escalation policy.

Difference between Escalation and Custom Outgoing Webhooks

 

More information on Custom Outgoing Webhooks can be found HERE.

Sample Scala Code for Reference

1
2
3
4
5
6
7
8
9
10
11
def generateSignature(url: String, auth_key: String, contents: Map[String, String]):
String={
val buffer = new StringBuilder(URL)
contents.toList.sorted foreach { case(k, v) =>
buffer.append(k)
buffer.append(v)
 
val hash = Crypto.signBytes(buffer.toString(), auth_key.getBytes)
Crypto.toBase64String(hash)
}
}

Updated on October 7, 2019

Was this article helpful?

Related Articles