Integrations
Service Pilot
Overview
This document provides a detailed guide to integrating ServicePilot with Callgoose SQIBS for real-time incident management, alert-driven incident creation, and automated incident resolution. The integration uses ServicePilot alerting policies to send webhook events to Callgoose SQIBS. Callgoose API Filters map incoming webhook JSON to incidents that are created, updated, and resolved automatically.
Prerequisites
- ServicePilot account with permissions to create Policies / Alert Policies and to configure notification actions.
- Callgoose SQIBS account with permissions to create API Tokens and API Filters.
- A Callgoose SQIBS Api endpoint and API token (generated from Callgoose).
- Network connectivity allowing ServicePilot outbound HTTPS POST to the Callgoose endpoint.
1. Obtain API Token and Endpoint Details (Callgoose SQIBS)
1.1 Generate an API Token
Create an API token in Callgoose SQIBS with the minimum required scopes to accept webhook events. Store the token securely; do not commit it to source control.
1.2 Find or Construct the Webhook Endpoint
Construct the Callgoose webhook endpoint that ServicePilot will POST to. Use a query parameter or header-based token per your security policy, and include a from or source parameter value such as ServicePilot to identify incoming requests in logs.
2. Configuring ServicePilot to Send Alerts
ServicePilot delivers alerts via Policies / Notification Actions. Configure a webhook destination and attach it to the alert policy(s) you want to forward to Callgoose.
2.1 Open the Alert / Policy Configuration
In ServicePilot:
- Go to Policies → Alert Policies (or Policies → Add a Policy → Alert Policies).
- Create or edit the alert policy that should notify Callgoose (for example, service downtime, metric threshold breach, or synthetic check failure).
2.2 Create a Webhook Notification / Action
Add a notification action that will send the policy’s alert as a webhook to Callgoose.
Recommended fields:
- Name: Callgoose SQIBS
- Type: Webhook / Custom Webhook
- Method: POST
- URL: <Callgoose webhook endpoint from section 1.2>
- Content-Type: application/json
- Headers: (optional) Authorization: Bearer <API_TOKEN> — or use query token
If ServicePilot supports a Test button for the webhook, use it to validate connectivity.
2.3 Define the JSON Payload Template
Use a predictable, compact JSON template so Callgoose API Filters can reliably parse keys. Replace the placeholder variables with ServicePilot’s template variables.
Recommended payload template:
{
"servicepilot_event_id": "<% event.id %>",
"source": "servicepilot",
"state": "<% event.state %>",
"severity": "<% event.severity %>",
"title": "<% event.title %>",
"description": "<% event.description %>",
"host": "<% target.host %>",
"service": "<% target.service %>",
"startTime": "<% event.start_time %>",
"endTime": "<% event.end_time %>",
"tags": {
"policy": "<% policy.name %>",
"policy_id": "<% policy.id %>"
},
"metadata": {
"console_link": "<% event.console_link %>"
}
}
Notes:
- Use a unique identifier (servicepilot_event_id, or composite keys like host + service + policy_id) so Callgoose can correlate trigger and resolve events.
- Ensure resolution events include the same identifier so the Resolve filter can match and close incidents.
2.4 Attach the Webhook to an Alert Policy
- In the Alert Policy configuration, add the Callgoose SQIBS webhook action under Notifications / Actions.
- Ensure the policy triggers on both problem and recovery states as required.
- Save the policy.
2.5 Send a Test
Use ServicePilot’s Test feature (if available) to:
- Validate that Callgoose receives the POST.
- Confirm JSON keys and values match your API Filter expectations.
- Confirm Callgoose returns a successful response status.
3. Example ServicePilot Webhook Payloads
3.1 Trigger / Problem Event
{
"servicepilot_event_id": "sp-evt-1001",
"source": "servicepilot",
"state": "CRITICAL",
"severity": "HIGH",
"title": "High CPU Usage - payments-service",
"description": "CPU > 90% for 5 minutes on payments-service",
"host": "payments-01",
"service": "payments-service",
"startTime": "2025-11-24T07:30:00Z",
"tags": {
"policy": "High CPU Alert",
"policy_id": "pol-77"
},
"metadata": {
"console_link": "servicepilot-console-link"
}
}
3.2 Resolve / Recovery Event
{
"servicepilot_event_id": "sp-evt-1001",
"source": "servicepilot",
"state": "OK",
"severity": "INFO",
"title": "CPU Normal - payments-service",
"description": "CPU returned to normal",
"host": "payments-01",
"service": "payments-service",
"startTime": "2025-11-24T07:30:00Z",
"endTime": "2025-11-24T07:40:00Z",
"tags": {
"policy": "High CPU Alert",
"policy_id": "pol-77"
}
}
4. Configuring Callgoose SQIBS
Create API Filters in Callgoose SQIBS to map incoming ServicePilot webhook payloads into incidents.
4.1 Create API Filters
4.1.1 Trigger Filter (Creating Incidents)
- Payload JSON Key: "state"
- Key Value Contains: [CRITICAL, ALARM, PROBLEM]
- Map Incident With: "servicepilot_event_id"
- Incident Title: "title"
- Incident Description: "description" (or leave empty to recieve full payload)
This filter creates a new incident when ServicePilot sends a problem state.
4.1.2 Resolve Filter (Auto-Resolving Incidents)
- Payload JSON Key: "state"
- Key Value Contains: [OK, RESOLVED, RECOVERY]
- Incident Mapped With: "servicepilot_event_id" (must match trigger mapping)
When ServicePilot sends a recovery/OK event for the same servicepilot_event_id, Callgoose will auto-resolve the incident.
Refer to the API Filter Instructions and FAQ for more details.
5. Testing and Validation
5.1 Triggering Alerts in ServicePilot
- Create a test Policy or lower thresholds to generate an alert.
- Confirm ServicePilot sends a webhook and Callgoose receives it in API logs.
- Verify a new incident is created with the expected title, description, and mapped identifier.
5.2 Resolving Alerts
- Allow the condition to recover or manually mark the alert as recovered in ServicePilot.
- Confirm ServicePilot sends a recovery webhook and Callgoose auto-resolves the matching incident.
6. Debugging and Troubleshooting
Common issues and how to resolve them
- No incident created
- Verify ServicePilot webhook delivery logs and call result (was the POST successful?).
- Confirm the Callgoose endpoint and token are correct.
- Ensure the Trigger Filter key/value (e.g., state) matches the payload value sent by ServicePilot.
- Incident not resolving
- Check that the Resolve event uses the same servicepilot_event_id (or mapping key) as the Trigger.
- Confirm Resolve Filter looks for the state value ServicePilot uses for recovery (e.g., OK).
- Malformed JSON or missing fields
- Inspect the exact JSON shown in Callgoose API request logs and update the ServicePilot payload template or Callgoose Filter mappings accordingly.
- Authentication / 401
- Confirm token placement (query vs header) matches Callgoose's expectation; if using headers, ensure ServicePilot supports custom headers on webhook actions.
- Network / TLS problems
- Ensure ServicePilot can reach the Callgoose endpoint over HTTPS and that there are no outbound firewall restrictions.
7. Security Considerations
- Use HTTPS for webhook delivery.
- Prefer sending the API token in a secure Authorization header if ServicePilot supports custom headers; otherwise use a short-lived token or restrict token permissions.
- Rotate API tokens periodically.
- Limit the scope/permissions of the integration token in Callgoose.
- Log and monitor incoming webhook requests in Callgoose to detect anomalies.
8. Conclusion
Following the steps in this document will enable reliable integration of ServicePilot with Callgoose SQIBS for automated incident creation and resolution. By configuring a focused JSON payload in ServicePilot and mapping fields via Callgoose API Filters (Trigger and Resolve), teams get deterministic, end-to-end automation from observability alerts to incident management.
For further customization or advanced use cases, refer to the official documentation for both Service Pilot and Callgoose SQIBS:
