Ruleset Management and Event Handling

Ruleset Management and Event Handling enables automated incident creation by defining custom rules that respond to specific event conditions. When a rule is triggered, it can execute predefined actions — such as sending an HTTP request to a Pinghome webhook — which then initiates an incident.

This feature allows seamless integration with third-party platforms like AWS, GCP, Azure, or any service capable of sending outbound webhooks. As a result, your system can respond automatically to threshold breaches, service failures, or alert events without manual intervention.

Key capabilities:
  • Create dynamic rulesets — Define rules based on tags, payload contents, or event metadata.
  • Trigger incident workflows — Automatically generate and track incidents based on incoming events.
  • Integrate with external tools — Connect monitoring, logging, or cloud platforms directly to Pinghome's incident system using webhook endpoints.
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
Retrieve all rulesets configured for your team and organization by calling this endpoint. Each ruleset contains information such as the rule type, name, description, urgency level, and assigned responders (e.g., teams).

The response is grouped into two scopes: team and organisation, showing rules defined at different levels of your environment.

Use cases:
  • Ruleset overview — View all active rules that determine how incidents are created from incoming events.
  • Responsibility auditing — Check which teams are assigned to respond when a specific rule is triggered.
  • Urgency validation — Review urgency settings to ensure incidents are prioritized appropriately based on rule definitions.


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/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
Create a new ruleset in the incident management system by submitting a configuration payload in the request body. The ruleset defines the logic for automatically generating incidents when specific conditions are met.

Required fields typically include the type of rule (e.g., state-change), an array of conditions, the target team_id or assignees, urgency level, and a descriptive name and description for context.

Once created, this ruleset becomes active and will automatically evaluate incoming events according to the defined logic.

Use cases:
  • Proactive alerting — Define custom logic to convert alert data into actionable incidents automatically.
  • Team-based triage — Assign rules to specific teams to ensure incidents are routed to the right responders based on the rule's criteria.
  • Flexible escalation logic — Configure different urgency levels and descriptions depending on the nature of the matched condition.

To review existing rules, see Get Rulesets.
To delete an existing rule, use Delete Ruleset.

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/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);
});
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).
Update Ruleset
Update an existing ruleset in the incident management system by providing the ruleset_id in the path and submitting the updated rule configuration in the request body. You can modify fields such as the type of the rule (e.g., state-change), the list of conditions, urgency, description, name, and assigned assignees (e.g., team IDs).

This endpoint is useful for refining how and when incidents are triggered, adjusting team responsibilities, or evolving your alert routing logic as infrastructure or workflows change.

Use cases:
  • Policy adjustments — Modify existing rules to reflect updated monitoring logic or operational policies.
  • Team ownership changes — Reassign incident ownership by updating team IDs or assignee lists.
  • Priority tuning — Adjust urgency levels and descriptions to better align with your response process.

To view current rules, see Get Rulesets.
To create new rules, use Create Ruleset.

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/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);
});
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).
Delete Ruleset
Delete an existing ruleset from the incident management system by providing its ruleset_id in the path. Once removed, the ruleset will no longer trigger incidents based on its defined conditions.

This is useful for cleaning up deprecated logic, test rules, or automation paths no longer needed in your incident workflows.

Use cases:
  • Legacy rules cleanup — Remove rulesets that no longer match your current infrastructure or alerting needs.
  • Test configuration removal — Delete temporary rules created during integration or staging setups.

To review or identify rules before deletion, see Get Rulesets.

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/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);
});
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).
Get Ruleset Actions
Retrieve all actions associated with a specific ruleset by providing its ruleset_id in the path. Each action defines what automated task should be executed when the ruleset conditions are met — such as updating a status page component or triggering a downstream system.

The response includes the action type (e.g., trigger-statuspage-update) and nested settings that specify the source (e.g., a resource ID being monitored), the target (such as a status page component), and the parent entity (e.g., the linked status page).

Use cases:
  • Status page automation — Automatically reflect service impact by linking monitored resources to status page components.
  • Rule-action mapping review — Confirm how each ruleset is wired to act when conditions are triggered.
  • Integration debugging — Inspect exact settings to verify IDs and types used in external updates or webhooks.


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/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);
});
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).
Update Ruleset Actions
Update the list of actions associated with a specific ruleset by providing the ruleset_id in the path and submitting the updated actions array in the request body. Each action includes a type (such as trigger-statuspage-update) and corresponding settings.

This endpoint is essential for refining or replacing automation behavior tied to incident rules. For example, you might update which status page components are affected when a rule triggers.

Use cases:
  • Automation updates — Modify how triggered incidents affect external tools like status pages or third-party integrations.
  • Integration corrections — Update resource, component, or parent references when IDs or structure change.
  • Rule-action realignment — Reassign an action to new targets as incident response strategies evolve.

To review the current actions tied to a ruleset before making updates, use the Get Ruleset Actions endpoint.

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/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);
});
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).
Get Webhooks
Retrieve a list of all webhook endpoints configured for the incident management service. Each webhook acts as an entry point for receiving external event data (e.g., from cloud alerts, logging tools, or custom systems) that can trigger automated incident creation based on predefined rules.

The response includes details for each webhook, such as name, description, enabled status, the URL to which events should be sent, and the created_at timestamp.

Use cases:
  • Integration inventory — View all active webhook endpoints used for event ingestion.
  • Debugging setup — Confirm webhook URLs, statuses, and metadata when testing third-party integrations.
  • Maintenance review — Identify old or disabled webhooks that may no longer be in use.

To add new webhook receivers for external events, use the Create Webhook endpoint.

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/v1/webhooks";

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).
Get Webhook Events
Retrieve a list of events received by a specific webhook by providing its webhook_id in the path. Each event represents a payload submitted to the webhook endpoint — typically from an external system or alerting service.

The response includes metadata such as the content_type of the payload, the raw body of the received request, the sender’s IP address, and the received_at timestamp.

You can use query parameters like last_received_at and limit to paginate results and retrieve only the most recent entries.

Use cases:
  • Integration troubleshooting — View the actual payloads and metadata received to debug malformed requests or failures.
  • Webhook activity audit — Track which external systems have submitted events and when.
  • Payload inspection — Validate the structure and content of incoming webhook data before mapping it to rulesets.

To view all available webhook endpoints in your system, see Get Webhooks.

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/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);
});
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 Webhook
Create a new webhook endpoint for the incident service by submitting the required configuration in the request body. A webhook acts as a custom entry point for external systems (e.g., cloud providers, CI/CD tools, alerting platforms) to send events that may trigger incidents based on ruleset evaluation.

You can define properties such as the name, description. After creation, the webhook’s unique id will be returned in the response. This ID can be used to programmatically submit event payloads to the webhook via the Submit Webhook Event endpoint

Use cases:
  • Third-party alert ingestion — Accept alert data from platforms like AWS, GCP, or GitHub Actions into your incident workflow.
  • Custom monitoring integration — Create webhook endpoints for internal tools to trigger incidents in real time.
  • Event-driven automation — Streamline operational response by forwarding external events to your ruleset system.

To inspect or manage existing webhooks, use Get Webhooks.

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/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);
});
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).
Submit Webhook Event Data
Submit event data to a specific webhook by providing the webhook_id in the path. This ID is returned when a webhook is created via the Create Webhook endpoint.

The request body accepts a flexible JSON payload consisting of arbitrary key-value data. Once submitted, the event will be processed by the webhook engine and evaluated against any matching rulesets to determine whether an incident should be triggered.

Use cases:
  • Trigger incidents from external systems — Submit alerts or event payloads from cloud providers, log systems, or internal tools.
  • Custom monitoring workflows — Report failures, anomalies, or health checks via automation scripts using a valid webhook ID.
  • Payload-driven automation — Drive incident creation logic based on dynamic field values submitted with each event.


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/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);
});
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).