Integrations
IBM Instana
Overview
This document provides a detailed guide to integrating IBM Instana with Callgoose SQIBS for real-time Incident Management, Incident Auto Remediation, and Event-Driven Automation.
With this integration, alerts generated in IBM Instana automatically create, update, and resolve incidents inside Callgoose SQIBS. This document covers configuring Instana’s Generic Webhook alert channel, defining a clean JSON payload, creating API Filters in Callgoose SQIBS, testing the flow, and troubleshooting.
Prerequisites
Before you begin, ensure the following:
- IBM Instana Account
- You must have permissions to access Alert Channels and Alerts (Global or Team Settings privileges).
- Callgoose SQIBS Account
- You need permission to create API Tokens and API Filters.
- Callgoose Webhook Endpoint & API Token
- These will be required to receive Instana events.
- Network Access
- Instana’s backend must be able to POST to your Callgoose webhook URL.
1. Obtain API Token and Endpoint Details (Callgoose SQIBS)
1.1 Generate an API Token
Create an API token inside Callgoose SQIBS. Save it securely, as it will be appended to the webhook URL or used in request headers from Instana.
1.2 Find or Construct the Webhook Endpoint
Your Callgoose SQIBS API endpoint generally follows this pattern:
https://<ORG>.callgoose.com/v1/process?from=Instana&token=<API_TOKEN>
- Replace <ORG> with your company/org name.
- Replace <API_TOKEN> with the generated token.
The from parameter helps identify Instana as the source in logs.
2. Configuring IBM Instana to Send Alerts
Instana sends notifications via Alert Channels. You will configure a Generic Webhook alert channel and attach it to Instana alert rules.
2.1 Open the Alert Channel Configuration
In Instana:
- Go to Settings.
- Open Global Settings → Events & Alerts.
- Go to Alert Channels.
- Click Add Alert Channel.
- Select Generic Webhook.
2.2 Create the Webhook Channel
Configure the following:
- Name:
- Callgoose SQIBS
- Webhook URL:
- The Callgoose endpoint from section 1.2.
- HTTP Method:
- POST
- Content Type:
- application/json
- Custom Headers (optional):
- Instana supports:
- Authorization: Bearer <API_TOKEN>
- x-api-key: <API_TOKEN>
- OAuth authentication for webhook channels (optional)
You may use query token or header token—either works.
2.3 Define the JSON Payload Template
Instana allows custom webhook bodies. Using a clean, predictable structure is recommended.
Use a template similar to the one below (variable names vary based on your Instana environment; adjust as needed):
{
"instana_event_id": "${event.id}",
"state": "${event.state}",
"severity": "${event.severity}",
"title": "${event.title}",
"description": "${event.description}",
"entity": {
"id": "${entity.id}",
"type": "${entity.type}",
"name": "${entity.name}"
},
"startTime": "${event.startTime}",
"endTime": "${event.endTime}",
"link": "${event.consoleLink}",
"metadata": {
"rule": "${rule.name}",
"source": "Instana"
}
}
This structure ensures consistency when writing Callgoose API Filters.
2.4 Attach the Webhook to an Alert
To ensure alerts are delivered:
- Go to Settings → Alerts.
- Create a new alert or edit an existing rule.
- Add the Callgoose SQIBS webhook channel as a notification target.
- Save the alert rule.
2.5 Send a Test
Instana provides a Test button on webhook channels.
Use this to confirm Callgoose receives events.
3. Example Instana Webhook Payloads
3.1 Trigger / Open Event
{
"instana_event_id": "evt-1001",
"state": "OPEN",
"severity": "CRITICAL",
"title": "High Memory Usage - payments-service",
"description": "Memory usage at 92% for the last 5 minutes.",
"entity": {
"id": "svc-44",
"type": "service",
"name": "payments-service"
},
"startTime": "2025-11-24T07:30:00Z",
"link": "https://instana.local/events/evt-1001"
}
3.2 Resolve Event
{
"instana_event_id": "evt-1001",
"state": "CLOSED",
"severity": "INFO",
"title": "High Memory Usage Resolved - payments-service",
"description": "Memory dropped back to 45%.",
"entity": {
"id": "svc-44",
"type": "service",
"name": "payments-service"
},
"startTime": "2025-11-24T07:30:00Z",
"endTime": "2025-11-24T07:40:00Z",
"link": "https://instana.local/events/evt-1001"
}
4. Configuring Callgoose SQIBS
4.1 Create API Filters
4.1.1 Trigger Filter (Creating Incidents)
- Payload JSON Key: state
- Key Value Contains: OPEN (or any Instana value that indicates an active event)
- Map Incident With: instana_event_id (Ensures correlation between open and resolved events)
- Incident Title: title
- Incident Description: description
4.1.2 Resolve Filter (Auto-Resolving Incidents)
- Payload JSON Key: state
- Key Value Contains: CLOSED (or Instana’s equivalent resolved state)
- Incident Mapped With: instana_event_id (Must match Trigger filter mapping)
This ensures that when Instana sends a resolved event, the corresponding incident is resolved automatically.
5. Testing & Validation
5.1 Triggering Alerts in Instana
- Temporarily modify alert thresholds,
- Or intentionally create an alert condition,
- Or use Instana’s “Test Webhook” function.
Verify that:
- Instana shows the webhook was sent successfully.
- Callgoose API logs display the received payload.
- A new incident appears in Callgoose SQIBS.
5.2 Resolving Alerts
Clear the alert condition or restore original thresholds.
Verify that:
- Instana sends a resolved event.
- Callgoose resolves the incident tied to the instana_event_id.
6. Debugging & Troubleshooting
Common Issues and Fixes
No Incident Created
- Incorrect webhook URL
- Wrong field in Trigger Filter (e.g., expecting firing instead of OPEN)
- Missing API token or incorrect token authentication
- Incorrect JSON key path in filter
Incident Not Resolving
- Resolve Filter mapping uses a different external id than the Trigger Filter
- Instana did not send a CLOSED or resolved event
- Payload structure differs from expected template
Malformed JSON
- Missing commas or braces in Instana custom payload
- Unsupported variable names in Instana template
Authentication Errors
- If using header auth, ensure headers are added correctly in Instana
- If using query tokens, ensure no extra characters or URL encoding issues
7. Security Considerations
- Always use HTTPS for webhook delivery.
- Prefer Authorization headers instead of exposing tokens in URLs if your team follows stricter security standards.
- Rotate API tokens regularly.
- Limit the permissions of the token used for integrations.
- Restrict outbound webhook access to Callgoose endpoints only.
8. Conclusion
By completing the steps above, you can successfully integrate IBM Instana with Callgoose SQIBS to enable automatic incident creation, updates, and resolution. This ensures a seamless observability-to-incident-management workflow and gives teams faster visibility into production issues.
For additional reference:
