Integrations
Icinga
Overview
This document provides a complete, beginner-friendly guide to integrating Icinga 2 with Callgoose SQIBS using direct webhook notifications.
Icinga 2 continuously monitors hosts and services. When it detects state changes such as CRITICAL, WARNING, or UNKNOWN, it will execute notification commands. By configuring a webhook-based notification command, Icinga can send JSON payloads directly to Callgoose SQIBS.
Callgoose will automatically create, update, and resolve incidents based on these payloads.
This integration enables:
- Real-time incident creation for Icinga alerts
- Automatic incident resolution when checks recover
- Flexible filtering and mapping using Callgoose API Filters
- End-to-end visibility from monitoring events → incident management
Prerequisites
Before proceeding, ensure you have the following:
- A running Icinga 2 instance (with Icinga Web 2 optional)
- The ability to modify Icinga configuration (/etc/icinga2/)
- A Callgoose SQIBS Webhook URL with API Token.
- Admin-level access to Callgoose SQIBS API Filters
- Basic understanding of Icinga objects: Notifications, Commands, Templates, Apply Rules
1. Install Icinga 2
Icinga provides officially supported repositories for major Linux distributions.
1.1. Install on Debian/Ubuntu
sudo apt update sudo apt install apt-transport-https wget gnupg wget -O - https://packages.icinga.com/icinga.key | sudo apt-key add - echo "deb https://packages.icinga.com/ubuntu icinga-$(lsb_release -sc) main" \ | sudo tee /etc/apt/sources.list.d/icinga.list sudo apt update sudo apt install icinga2 monitoring-plugins
Start and enable service:
sudo systemctl enable icinga2 sudo systemctl start icinga2
1.2. Install on RHEL / CentOS / AlmaLinux / Rocky
sudo rpm --import https://packages.icinga.com/icinga.key sudo tee /etc/yum.repos.d/icinga.repo<<EOF [icinga] name=Icinga Repository baseurl=https://packages.icinga.com/epel/$releasever/release/ enabled=1 gpgcheck=1 gpgkey=https://packages.icinga.com/icinga.key EOF
Install:
sudo yum install icinga2 monitoring-plugins sudo systemctl enable icinga2 sudo systemctl start icinga2
1.3. Verify Icinga Installation
icinga2 --version systemctl status icinga2 icinga2 daemon -C # Validate configuration
When the daemon reports No errors, installation is complete.
2. Obtain the Callgoose SQIBS Webhook URL
- Log in to Callgoose SQIBS
- Navigate to:
- Settings → Integrations → Webhooks / API
- Create a new webhook endpoint
- Copy the URL, for example:
https://<company>.callgoose.com/v1/process?from=icinga&token=xxxxx
- Keep the token secure. You will insert this inside the Icinga notification script.
3. Create the Icinga → Callgoose Webhook Notification
Icinga uses NotificationCommands to send alerts.
You will add:
- A shell script that sends JSON to Callgoose
- A NotificationCommand definition
- A Notification template
- An Apply rule that activates it for hosts/services
3.1 Create the Webhook Script
Create and save this file:
/etc/icinga2/scripts/notify-callgoose.sh
#!/bin/bash
HOST="$1"
SERVICE="$2"
STATE="$3"
OUTPUT="$4"
LONGOUTPUT="$5"
WEBHOOK_URL="https://<YOUR>.callgoose.com/v1/process?from=icinga&token=<TOKEN>"
json_payload=$(cat <<EOF
{
"source": "icinga2",
"host": "$HOST",
"service": "$SERVICE",
"status": "$STATE",
"summary": "$OUTPUT",
"description": "$LONGOUTPUT",
"timestamp": "$(date -Iseconds)"
}
EOF
)
curl -X POST \
-H "Content-Type: application/json" \
-d "$json_payload" \
"$WEBHOOK_URL"
Make it executable:
sudo chmod +x /etc/icinga2/scripts/notify-callgoose.sh
3.2 Create the NotificationCommand
Add this file:
/etc/icinga2/conf.d/notification-callgoose.conf
object NotificationCommand "callgoose-notify" {
import "plugin-notification-command"
command = [ "/etc/icinga2/scripts/notify-callgoose.sh" ]
arguments = {
host = "$host.name$"
service = "$service.name$"
state = "$service.state$"
output = "$service.output$"
longoutput = "$service.long_output$"
}
}
3.3 Create a Notification Template
template Notification "callgoose-template-service" {
command = "callgoose-notify"
states = [ OK, Warning, Critical, Unknown ]
types = [ Problem, Recovery ]
}
3.4 Apply Notification to Services
apply Notification "callgoose-service-notify" to Service {
import "callgoose-template-service"
assign where host.vars.enable_callgoose == true
}
Then enable it on a host:
object Host "web01" {
address = "192.168.1.10"
vars.enable_callgoose = true
}
4. Example Payloads Sent to Callgoose SQIBS
4.1 Trigger (Problem)
{
"source": "icinga2",
"host": "web01",
"service": "HTTP",
"status": "CRITICAL",
"summary": "Connection refused",
"description": "Service HTTP returned CRITICAL",
"timestamp": "2025-11-24T10:05:31Z"
}
4.2 Resolve (Recovery)
{
"source": "icinga2",
"host": "web01",
"service": "HTTP",
"status": "OK",
"summary": "HTTP service OK",
"description": "Recovered",
"timestamp": "2025-11-24T10:09:12Z"
}
5. Configure API Filters in Callgoose SQIBS
You must now map JSON keys to incident rules.
5.1 Trigger Filter – Create Incident
- Payload JSON Key: "status"
- Value Contains: [CRITICAL, WARNING, UNKNOWN]
- Map Incident With: "host"
- Incident Title From: "summary"
- Incident Description From: leave empty or use description
5.2 Resolve Filter – Resolve Incident
- Payload JSON Key: "status"
- Value Contains: OK
- Incident Mapped With: "host"
This will ensure the correct incident is resolved.
6. Testing the Integration
Step 1 — Trigger an alert
Stop a monitored service, for example:
sudo systemctl stop apache2
Icinga should detect CRITICAL → webhook → incident created.
Step 2 — Trigger recovery
sudo systemctl start apache2
Incident should auto-resolve.
Step 3 — Verify logs
- Icinga log: /var/log/icinga2/icinga2.log
- Callgoose Webhook Log section
- Validate that the JSON fields match your filter conditions
7. Troubleshooting
- No incident created
- Check if the script executed
- Ensure webhook URL and token are correct
- Verify Callgoose API Filters match your payload structure
- Incident not resolving
- Ensure resolve filter is set for status = OK
- Confirm host + service are identical to the firing event
- Icinga not sending notifications
- Verify notification apply rules
- Ensure the host has vars.enable_callgoose = true
- Check icinga2 daemon -C for config errors
- Webhook call fails
- Confirm network outbound access
- Test with a manual curl using the same JSON
8. Conclusion
You now have a complete webhook-based integration between Icinga 2 and Callgoose SQIBS, enabling automatic incident creation and automated resolution based on monitoring events. This setup ensures seamless monitoring → incident workflow automation with minimal maintenance.
For additional reference:
