Reset Search
 

 

Article

REST Endpoint

« Go Back

Information

 
Integration_Notes
The VictorOps REST Endpoint accepts alerts from any source via an HTTPS POST request. As long as you can send a POST request, you can generate alerts through VictorOps. For some working examples and use cases see here.

Only the message_type is required, but passing additional data will help you get the most benefit from the VictorOps platform.  

The alert fields must be sent as JSON in the body of the POST request.

Alert fields
 
Field nameDescriptionRequired
message_type[String] One of the following values: INFO, WARNING, ACKNOWLEDGEMENT, CRITICAL, RECOVERY

CRITICAL messages raise incidents in VictorOps, you can also configure your settings to raise incidents for WARNING messages.

INFO messages become part of your timeline but do not raise incidents.
entity_id[String] The name of alerting entity. If not provided, a random name will be assigned.

VictorOps uses the entity_id field to identify the monitored entity (host, service, metric, etc.) for rollup into incidents. If you don't provide an ID in your request, we'll assign one and return it as part of the response.

By using the same entity_id in multiple notifications, the incidents created can go through the normal incident lifecycle, from Triggered, through Acknowledged, to Resolved.

An example entity_id could be "<service>/<HostName>", i.e... "diskspace/db01.mycompany.com"
 
timestamp[Number] Timestamp of the alert in seconds since epoch. Defaults to the time the alert is received at VictorOps. 
state_start_time[Number] The time this entity entered its current state (seconds since epoch). Defaults to the time alert is received. 
state_message[String] Any additional status information from the alert item. 
monitoring_tool[String] The name of the monitoring system software (eg. nagios, icinga, sensu, etc.) 
entity_display_name[String] Used within VictorOps to display a human-readable name for the entity. 
ack_msg[String] A user entered comment for the acknowledgment. 
ack_author[String] The user that acknowledged the incident. 
 

Example alerts:

{
    "message_type":"CRITICAL",
    "entity_id":"disk space/db01.mycompany.com",
    "state_message":"the disk is really really full"
}

{
    "message_type":"RECOVERY",
    "entity_is_host":"y",
    "entity_id":"landru",
    "state_message":"host is up"
}

Response

The HTTP result code will indicate success or failure, with the following JSON values in the response body:
 
  • result: "success" or "failure"
  • entity_id: The id passed in with the POST request, or the id randomly assigned by VictorOps. You should continue to pass us this id for subsequent alerts that pertain to the same incident.
  • message: Error message (if any)

Example responses:

{
    "result":"success",
    "entity_id":"86dc4115-72d3-4219-9d8e-44939c1c409d"
}

or...

{
    "result":"failure",
    "message":"Missing fields: routing_key "
}

You can also invoke this with a cURL command like the following:

curl --data-binary '{"message_type":"critical",
"timestamp":"'$(date +%s)'",
"entity_id":"disk space"}' https://alert.victorops.com/integrations/generic/20131114/alert/[YOUR_API_KEY_HERE]/[ROUTING_KEY_HERE]


Enabling the REST Endpoint

Go to your VictorOps admin settings page and expand the integrations pane. Enable the "REST Endpoint" integration. The URL that you need to POST to will be displayed. If, for any reason, you need a new API key, revoke the old one and a new key will be issued.

User-added image 

Full Example:

For a code level client, check out this gist: https://gist.github.com/danielhopkins/7569899


Integration Examples:

Sensu
SalesForce
UserVoice

Feedback


 

Was this article helpful?


   

Feedback

Please tell us how we can make this article more useful.

Characters Remaining: 255