Ruleset Management and Event Handling

Ruleset management and event handling allows automated incident creation based on predefined rules. By configuring actions to send HTTP requests to your Pinghome webhook, incidents are generated automatically when specific conditions are met. This functionality supports integration with alerts from AWS, GCP, Azure, and other platforms, streamlining your incident management process and ensuring that incidents are effectively created and resolved.

ENDPOINTS

Expand all

Ruleset configuration and management
GET/rulesets
POST/ruleset
PUT/ruleset/{id}
DELETE/ruleset/{id}
GET/ruleset/{id}/actions
PUT/ruleset/{id}/actions
Webhook handling

Get Rulesets

This API endpoint retrieves the rulesets associated with the team or organization. The rulesets include information such as rule type, name, description, urgency, and assignees.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system will return ruleset data for both team and organization.
If the request is unauthorized, the system will return an authentication error message.

JavaScript

Response codes

const axios = require('axios');

const url = "https://incident-query.api.pinghome.io/default/v1/rulesets";

axios.get(url, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

ResponseThis section is used to view the possible HTTP response codes returned by the API. These codes indicate the status of a request, such as 201 (Created), 401 (Unauthorized), 409 (Conflict), or 422 (Unprocessable Entity).

Create Ruleset

This API endpoint allows creating a new ruleset in the incident service. The request body requires details such as the rule type, conditions, team ID, and other related information.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system will create a new ruleset and return the ruleset ID.
If the request is invalid, the system will return an error message with details of the invalid fields.

Request Body Parameters

rule_type string
The type of rule being created. Accepted values: 'state-change' or 'webhook'.
conditions array of objects
level string
team_id string
name string
description string
urgency string
assignees (optional) array of objects

JavaScript

Response codes

const axios = require('axios');

const url = 'https://incident-cmd.api.pinghome.io/default/v1/ruleset';
const data = {
  rule_type: 'state-change',
  conditions: [{ values: ['10'], operator: 'equal', type: 'json-check', key: 'products[0].count' }],
  level: 'team',
  team_id: 'c03b02ec-244f-4d2c-8f68-3910071ed5c8',
  name: 'Name',
  description: 'Description',
  urgency: 'medium',
  assignees: [{ type: 'team', id: '445a5c1f-c0eb-403a-96d7-3976e5dc74ed' }]
};

axios.post(url, data, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Update Ruleset

This API endpoint allows updating an existing ruleset in the incident service. The request body requires the rule type, conditions, team ID, and other related information.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system will update the ruleset and return a success message.
If the request is invalid, the system will return an error message with details of the invalid fields.

Path Parameters

id string
The ID of the ruleset to be updated. Example: 'c03b02ec-244f-4d2c-8f68-3910071ed5c8'

Request Body Parameters

rule_type string
The type of rule being created. Accepted values: 'state-change' or 'webhook'.
conditions array of objects
level string
team_id string
name string
description string
urgency string
assignees (optional) array of objects

JavaScript

Response codes

const axios = require('axios');

const url = 'https://incident-cmd.api.pinghome.io/default/v1/ruleset/c03b02ec-244f-4d2c-8f68-3910071ed5c8';
const data = {
  rule_type: 'state-change',
  conditions: [{ values: ['10'], operator: 'equal', type: 'json-check', key: 'products[0].count' }],
  level: 'team',
  team_id: 'c03b02ec-244f-4d2c-8f68-3910071ed5c8',
  name: 'Name',
  description: 'Description',
  urgency: 'medium',
  assignees: [{ type: 'team', id: '445a5c1f-c0eb-403a-96d7-3976e5dc74ed' }]
};

axios.put(url, data, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Delete Ruleset

This API endpoint allows deleting an existing ruleset in the incident service. The id of the ruleset to be deleted must be provided as a path parameter.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system will delete the specified ruleset and return a confirmation message.
If the request is unauthorized or the ruleset is not found, the system will return an error message.

Path Parameters

id string
The ID of the ruleset to be deleted. Example: 'c03b02ec-244f-4d2c-8f68-3910071ed5c8'

JavaScript

Response codes

const axios = require('axios');

const url = 'https://incident-cmd.api.pinghome.io/default/v1/ruleset/c03b02ec-244f-4d2c-8f68-3910071ed5c8';

axios.delete(url, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Get Ruleset Actions

This API endpoint retrieves the actions associated with a specific ruleset. The ruleset ID is provided as a path parameter.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system will return the actions tied to the ruleset, including action type and settings.
If the request is unauthorized, the system will return an authentication error message.

Path Parameters

id string
The unique ID of the ruleset for which actions are being retrieved. Example: 'c03b02ec-244f-4d2c-8f68-3910071ed5c8'

JavaScript

Response codes

const axios = require('axios');

const url = "https://incident-query.api.pinghome.io/default/v1/ruleset/c03b02ec-244f-4d2c-8f68-3910071ed5c8/actions";

axios.get(url, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Update Ruleset Actions

This API endpoint updates the actions for a specific ruleset. The id of the ruleset must be provided as a path parameter. The request body should contain the updated actions and their settings.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system will update the actions for the specified ruleset.
If the request is invalid, the system will return an error message with details of the invalid fields.

Path Parameters

id string
The ID of the ruleset to be updated. Example: '445a5c1f-c0eb-403a-96d7-3976e5dc74ed'

Request Body Parameters

actions array of objects
An array of actions to be updated, each containing an ID, type, and settings.

JavaScript

Response codes

const axios = require('axios');

const url = 'https://incident-cmd.api.pinghome.io/default/v1/ruleset/445a5c1f-c0eb-403a-96d7-3976e5dc74ed/actions';
const data = {
  actions: [
    {
      type: 'trigger-alerts',
      settings: [
        {
          status_page_id: '445a5c1f-c0eb-403a-96d7-3976e5dc74ed',
          component_id: '445a5c1f-c0eb-403a-96d7-3976e5dc74ed'
        }
      ]
    }
  ]
};

axios.put(url, data, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Get Webhooks

This API endpoint retrieves the list of webhooks created for the incident service.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system will return a list of webhooks with details such as webhook name, description, and URL.
If the request is unauthorized, the system will return an authentication error message.

JavaScript

Response codes

const axios = require('axios');

const url = "https://incident-query.api.pinghome.io/default/v1/webhooks";

axios.get(url, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Get Webhook Events

This API endpoint retrieves the events related to a specific webhook. The webhook ID is provided as a path parameter. Query parameters like last_received_at and limit can be used to control pagination and the number of events retrieved.

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system will return webhook event details such as content type, body, IP, and received time.
If the request is unauthorized, the system will return an authentication error message.

Path Parameters

id string
The unique ID of the webhook for which events are being retrieved. Example: 'c03b02ec-244f-4d2c-8f68-3910071ed5c8'

Query Parameters

limit (optional) positive integer
Specifies the maximum number of webhook events to return, such as '10'. You can choose to include this parameter as needed.
last_received_at (optional) string

JavaScript

Response codes

const axios = require('axios');

const url = "https://incident-query.api.pinghome.io/default/v1/webhook/c03b02ec-244f-4d2c-8f68-3910071ed5c8/events?limit=10&last_received_at=2024-03-15T19:09:39Z";

axios.get(url, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Create Webhook

This API endpoint creates a new webhook for the incident service..

Authorization: Bearer YOUR_TOKEN

Expected Behavior:

On success, the system will create a new webhook and return the webhook ID.
If the request is invalid, the system will return an error message with details of the invalid fields.

Request Body Parameters

name (optional) string
The name of the webhook. This parameter can be provided at your discretion.
description (optional) string

JavaScript

Response codes

const axios = require('axios');

const url = 'https://incident-cmd.api.pinghome.io/default/v1/webhook';
const data = {
  name: "Webhook name",
  description: "Webhook description"
};

axios.post(url, data, {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});

Submit Webhook Event Data

This API endpoint allows you to submit data to a specific webhook by providing the webhook ID in the path. The request body accepts arbitrary key-value data to be processed by the webhook.

Expected Behavior:

On success, the webhook will process the data and return a confirmation message along with additional meta information such as the IP address and content type.
If the webhook ID is invalid, an error message will be returned.

Path Parameters

id string
The unique ID of the webhook created earlier.

Request Body Parameters

body object
Key-value data to be submitted to the webhook.

JavaScript

Response codes

const axios = require('axios');

const url = 'https://data-gateway.api.pinghome.io/default/v1/incident/webhook/{id}';
const data = {
  example_key: 'example_value'
};

axios.post(url, data, {
  headers: {
    'Content-Type': 'application/json'
  }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error(error);
});