zenoss

Overview

This document provides a detailed guide to integrating Zenoss with Callgoose SQIBS for real-time Incident Management, event-driven alerting, and automated incident resolution.

The integration uses a Zenoss Notification Command (often a custom script or Webhook) to send alert event payloads directly to Callgoose. Callgoose API Filters convert these payloads into incidents that are automatically created and resolved upon event state changes.

Prerequisites

Before beginning, ensure you have the following:

• A Callgoose SQIBS account with permissions to create API Filters and access the integration endpoint.
• A Zenoss deployment (Cloud or On-Premise) with admin-level access to configure Notification Commands and Notification Triggers/Rules.
• A valid Callgoose API token and Api endpoint URL.
• A test Zenoss event or alert rule (recommended) for validating the payload and delivery.

1. Prepare Callgoose: Obtain Endpoint and Token

1.1 Retrieve Callgoose API Endpoint

Generate or locate your Callgoose process endpoint:

https://****.callgoose.com/v1/process?from=Zenoss=xxxx

Store the API token securely and never commit it to source control.

2. Configure Zenoss Notification Command (Webhook)

Zenoss typically uses a Notification Command to define what action should occur when an event is triggered. We will configure a command to send an HTTP POST request (Webhook) to Callgoose.

2.1 Create the Zenoss Notification Command

Navigate to Events →Settings → Notification Commands (or equivalent path in your Zenoss version).

Create a new command, often using a scripting language like Python or a shell command utilizing curl to construct and send the JSON payload.

2.2 Configure the Webhook Fields (via curl or script)

The command must construct a JSON body that includes crucial fields for Callgoose to map and resolve incidents.

• URL: The Callgoose endpoint from Step 1.
• Method: POST
• Headers: Content-Type: application/json

3. Example Zenoss Payloads

The JSON payload you construct in your Notification Command must contain keys that Callgoose can use for mapping. The two most critical fields are the unique identifier (for mapping/resolution) and the status.

Firing/Trigger Payload Example (Event State is not Clear):

JSON

{
  "event_status": "${evt/status}", 
  "event_id": "${evt/evid}", 
  "summary": "${evt/summary}",
  "severity": "${evt/severity}",
  "device_name": "${evt/device}",
  "first_time": "${evt/firstTime}"
}

Key for Triggering: event_status will have values like 2 (New), 3 (Acknowledged), or 4 (Suppressed).

Resolved State Example (Event State is Clear):

When the original event clears in Zenoss, the status changes to 0 (Clear). The payload must contain this status and the original unique ID.

JSON

{
  "event_status": "${evt/status}", 
  "event_id": "${evt/evid}", 
  "summary": "RESOLVED: ${evt/summary}",
  "cleared_time": "${evt/clearedTime}"
}

Key for Resolution: event_status will have the value 0.

inspect your actual payloads inside Callgoose API Log and use those fields in your API Filter mappings.

4. Configure Zenoss Notification Trigger

After defining the command, you need a Notification Trigger/Rule to tell Zenoss when to execute the command.

4.1 Create the Notification Trigger

1. Navigate to Events → Settings →Notification Triggers (or equivalent).
2. Create a new trigger.
3. Filter/Rule: Define the conditions (e.g., severity grater than or equal to Warning, or specific Device Classes) that should cause an alert.
4. Action: Link the trigger to the Callgoose_Integration_Webhook command created in Step 2.
5. Repeat on Clear: Crucially, ensure the trigger is configured to execute the command when the event is cleared (status = 0) to send the resolution payload.

5. Create API Filters in Callgoose SQIBS

Callgoose API Filters convert incoming Zenoss webhooks into incidents.

You will need to use two main filters: a Trigger Filter (to create the incident) and a Resolve Filter (for auto-resolution).

5.1 Trigger Filter — Create Incident

This filter analyzes the incoming Zenoss payload and creates a new incident in Callgoose if the event is actively firing or acknowledged.

• Payload JSON Key: "event_status"
• Key Value Contains: 2 or 3
• Map Incident With: "event_id"
• Incident Title: " summary"
• Incident Description: (Optional)
• (Rationale: You can leave this empty to use the full JSON payload as the description, or map specific fields like device_name or severity for a cleaner display.)

5.2 Resolve Filter — Auto-Resolve Incident

This filter watches for the clear/resolved status from Zenoss to automatically close the corresponding incident in Callgoose.

• Payload JSON Key: event_status
• Rationale: Again, using the Zenoss event status field.
• Key Value Contains: 0
• Rationale: Zenoss status code 0 signifies that the event has been cleared or resolved.
• Incident Mapped With: event_id
• Rationale: This must match the key used in the Trigger Filter. It allows Callgoose to locate the active incident created earlier and resolve it.

6. Verify and Test the Integration

After configuring both the Zenoss Notification Command/Trigger and the Callgoose API Filters, it is essential to verify that the entire process chain is working correctly.

6.1 Test Initial Delivery

The first step is to confirm that the Zenoss system successfully sends the data to the Callgoose endpoint.

• Create a broad test filter in Callgoose. This temporary filter should have very permissive settings (e.g., matching any payload) to ensure that any incoming data is logged.
• Manually trigger a test event in Zenoss (or wait for an event that matches your configured Trigger rules).
• Confirm Callgoose receives the payload in its API Logs. If the payload appears, you have confirmed network connectivity and the correct Callgoose API token/URL are in use.

6.2 View Exact Payload

Before relying on the final filters, you must ensure the field names in your Callgoose filters exactly match the field names in the JSON payload sent by Zenoss.

• Use Callgoose’s API request logs to inspect the exact JSON payload sent by your Zenoss Notification Command.
• Copy field names directly from these logs (e.g., confirm it's event_id and not eventId) for accurate configuration of the Trigger and Resolve filters.

6.3 Final Verification

This step tests the full, end-to-end functionality, ensuring incidents are created and automatically closed.

• Trigger an alert in Zenoss (ensure the Event Status is not equal to 0, e.g., status 2 or 3).
• A new Incident should be created in Callgoose via the Trigger Filter.
• Clear the event condition in Zenoss(Event Status must change to = 0).
• The corresponding Incident should be auto-resolved in Callgoose via the Resolve Filter.
• Confirm mapping consistency by ensuring the same event_id value was used both for creating and resolving the incident.

7. Troubleshooting

If your integration does not work as expected, use this guide to diagnose common issues between Zenoss and Callgoose SQIBS.

Incoming Payload Not Received

If Callgoose is not logging any incoming request in the API Logs:

• Potential Zenoss Check:
• Check the Zenoss Notification Command log or output for execution errors. If you used a script (like Python or Shell), verify that the script ran successfully and that the curl command or HTTP request function executed without network errors.
• Verify the Callgoose endpoint URL and API token stored in your Zenoss command are exactly correct and accessible.
• Confirm HTTPS connectivity is successful (no SSL/TLS errors).
• Potential Callgoose Check:
• Verify the endpoint URL and token again. A single typo will prevent delivery.
• If using an intermediary network component (proxy, firewall), ensure it is not blocking the traffic from your Zenoss server to the Callgoose domain.

Incidents Not Auto-Resolving

If incidents are created successfully when an alert fires, but remain open after the alert clears in Zenoss:

• Potential Zenoss Check:
• Check if Zenoss is actually configured to send the notification when the event clears. The Notification Trigger must be configured to execute the command when the event status changes to 0.
• Inspect the payload Zenoss sent upon clearance to ensure the key event_status was correctly populated with the value 0.
• Potential Callgoose Check:
• Ensure the Resolve Filter is active and its Payload JSON Key is set to event_status and Key Value Contains is set to 0.
• Crucially, confirm that the value used in Incident Mapped With (e.g., the specific value of event_id) in the Resolve Filter exactly matches the one used by the Trigger Filter for the corresponding incident.

Wrong or Missing Payload Fields

If Callgoose receives the payload but the resulting incident title or mapping is incorrect:

• Potential Zenoss Check:
• If you are dynamically populating the JSON body using Zenoss variables (e.g., ${evt/summary}), inspect the output of your Notification Command (by temporarily logging the payload to a file) to see what Zenoss variables are populating. You may find a variable is empty or incorrect.
• Ensure there are no quoting errors in your curl command or script that are malforming the JSON structure.
• Potential Callgoose Check:
• Inspect the live payload in the Callgoose API logs.
• Update your API Filters to match the exact field structure and case-sensitivity seen in the logs.

8. Conclusion

Integrating Zenoss with Callgoose SQIBS enables fully automated incident creation and resolution based on infrastructure and application events. By configuring a robust Zenoss Notification Command and mapping the payloads through Callgoose API Filters, teams gain real-time visibility into system degradation.

With clean Trigger and Resolve filters, this integration ensures that critical Zenoss events instantly become actionable incidents—and clearing the event automatically closes the loop, improving operational reliability.

For further customization or advanced use cases, refer to:

• zenoss documentation
• Callgoose SQIBS API Token Documentation
• Callgoose SQIBS API Endpoint Documentation
• API Filter Instructions and FAQ
• How to Send API