Integrations
Serverless
Overview
This document provides a detailed guide to integrating the Serverless Framework with Callgoose SQIBS for real-time Incident Management, Incident Auto Remediation, and Event-Driven Automation. The integration enables automatic creation, updating, and resolution of incidents in Callgoose SQIBS based on errors or specific events triggered within your Serverless functions (AWS Lambda, Azure Functions, etc.).
The guide includes steps for installing the framework, configuring function handlers to dispatch alerts, creating API filters in Callgoose SQIBS, and troubleshooting.
Prerequisites
- Serverless Framework: Installed and configured with valid cloud provider credentials (e.g., AWS, Azure, Google Cloud).
- Callgoose SQIBS Account: With valid privileges to set up API filters and receive notifications.
- Webhook/API Endpoint: Available in Callgoose SQIBS to receive alerts from the Serverless function.
1. Obtain API Token and Endpoint Details
To integrate with Callgoose SQIBS, you first need to obtain an API token and find the API endpoint details.
- Generate an API Token: Follow the guide on How to Create API Token in Callgoose SQIBS.
- Find the API Endpoint: Refer to the Callgoose SQIBS API Endpoint Documentation to get the endpoint details where the JSON payloads from your Serverless function will be sent.
2. Installing Serverless Framework
First, you need to ensure the Serverless Framework is installed. If you haven't installed it yet, follow these steps.
2.1. Install via NPM (Node Package Manager)
The standard method for installing Serverless is via npm.
Shell:
# 1. Install Serverless globally npm install -g serverless # 2. Create a new service (if you don't have one) serverless create --template aws-nodejs --path my-service cd my-service # 3. Install axios for HTTP requests (required for the integration) npm install axios
3. Configuring the Alert Pipeline
This section details how to configure your Serverless function to forward errors or events to Callgoose SQIBS. Unlike pre-built tools, we will implement a robust error-handling wrapper or logic within the function.
3.1. Configure serverless.yml
You need to inject your Callgoose credentials as environment variables. This ensures your code remains clean and secure.
File: serverless.yml
service: callgoose-integration
provider:
name: aws
runtime: nodejs18.x
environment:
CALLGOOSE_API_URL: https://****.callgoose.com/v1/process?from=Buildkite
# Best Practice: Fetch this from AWS Secrets Manager or SSM Parameter Store in production
CALLGOOSE_API_TOKEN: ${env:CALLGOOSE_API_TOKEN}
functions:
criticalProcess:
handler: handler.runProcess
events:
- schedule: rate(10 minutes)
3.2. Implement the Alert Logic (Node.js Example)
We will create a standard JSON structure for our alerts. This structure is critical for configuring the API Filters in Section 4.
File: handler.js
const axios = require('axios');
// Helper function to format and send the event (Trigger or Resolve)
const sendCallgooseEvent = async (status, message, context, error = null) => {
const payload = {
source: "serverless-function",
status: status, // "firing" or "resolved"
service: process.env.AWS_LAMBDA_FUNCTION_NAME || "unknown-service",
alert_name: error ? (error.name || "Error") : "Recovery",
message: message,
request_id: context.awsRequestId,
timestamp: new Date().toISOString(),
stack_trace: error ? error.stack : "N/A"
};
try {
await axios.post(process.env.CALLGOOSE_API_URL, payload, {
headers: {
'Authorization': `Bearer ${process.env.CALLGOOSE_API_TOKEN}`,
'Content-Type': 'application/json'
}
});
console.log(`Event (${status}) sent to Callgoose SQIBS`);
} catch (err) {
console.error("Failed to send event:", err.response ? err.response.data : err.message);
}
};
module.exports.runProcess = async (event, context) => {
try {
// --- Your Business Logic Here ---
const isSystemHealthy = false; // Simulating a failure
if (!isSystemHealthy) {
throw new Error("Critical DB Connection Timeout");
}
// If logic succeeds (and you have state management to know it previously failed):
// await sendCallgooseEvent("resolved", "System Recovered", context);
// --------------------------------
return { statusCode: 200, body: "Success" };
} catch (error) {
// Catch the error and send "firing" status to Callgoose
await sendCallgooseEvent("firing", error.message, context, error);
// Rethrow if you want Lambda to mark it as failed in CloudWatch
throw error;
}
};
4. Configuring Callgoose SQIBS
4.1 Create API Filters in Callgoose SQIBS
To correctly map incidents from the Serverless alerts, you need to create API filters based on the JSON payloads received.
4.1.1 Example JSON Payloads from Serverless
Based on the code in Section 3.2, here are the exact JSON payloads Callgoose SQIBS will receive.
Alert Triggered JSON:
{
"source": "serverless-function",
"status": "firing",
"service": "callgoose-integration-dev-criticalProcess",
"alert_name": "Error",
"message": "Critical DB Connection Timeout",
"request_id": "c6afb2e0-988b-51ab-7583fb27",
"timestamp": "2025-10-17T12:55:37Z",
"stack_trace": "Error: Critical DB Connection Timeout\n at Runtime.module.exports.runProcess..."
}
Alert Resolved JSON:
{
"source": "serverless-function",
"status": "resolved",
"service": "callgoose-integration-dev-criticalProcess",
"alert_name": "Recovery",
"message": "System Recovered",
"request_id": "d8bfb2e1-221c-41ab-8821-fb2751ab7583",
"timestamp": "2025-10-17T13:00:00Z",
"stack_trace": "N/A"
}
4.2 Configuring API Filters
4.2.1 Integration Templates
If you see a Serverless integration template in the "Select Integration Template" dropdown in the API filter settings, you can use it. Otherwise, follow the manual configuration below.
4.2.2 Manually Add/Edit the Filter
Trigger Filter (For Creating Incidents):
- Payload JSON Key: status
- Key Value Contains: [firing]
- Map Incident With: service
- Note: Mapping with "service" groups all errors from this specific function into one incident. If you want a separate incident for every single execution error, use "request_id".
- Incident Title From: message
- Result Example: "Critical DB Connection Timeout"
- Incident Description From: stack_trace
- Result Example: The full stack trace will be shown in the incident description for easier debugging.
Resolve Filter (For Resolving Incidents):
- Payload JSON Key: status
- Key Value Contains: [resolved]
- Incident Mapped With: service
- Note: This must match the "Map Incident With" field in the Trigger Filter (e.g., "service") to correctly identify and close the open incident.
Refer to the API Filter Instructions and FAQ for more details.
4.3 Finalizing Setup
- Save the API Filters: Ensure that the filters are correctly configured and saved in Callgoose SQIBS.
- Double check that all key mappings, incident titles, and descriptions are correctly aligned with the payload structure defined in your handler.js.
5. Verifying the Integration
You can now verify that the integration is working for both creating and resolving incidents.
5.1 Triggering an Incident
- Run Test: Manually invoke your function locally or on the cloud to force the error condition. Shell:
# Set token locally for testing export CALLGOOSE_API_TOKEN=your_token_here # Invoke the function locally serverless invoke local --function criticalProcess
- Verify Dashboard: Log in to your Callgoose SQIBS platform. You should see a new alert titled "Critical DB Connection Timeout".
5.2 Resolving the Incident
- Modify Code: Temporarily uncomment the resolution line in handler.js and set isSystemHealthy = true.
// Update this variable to test success path
const isSystemHealthy = true;
// ...
// Uncomment this line to test resolution
await sendCallgooseEvent("resolved", "System Recovered", context);
- Run Test Again:
serverless invoke local --function criticalProcess
- Verify Dashboard: The previously created incident should now be marked as Resolved automatically.
6. Debugging and Troubleshooting
You can enable debugging in the API tokens used with Serverless notifications for troubleshooting purposes.
- Enable Debugging: You can update the debug value when adding or updating an API token.
- When API tracking is enabled, logs are stored in the API log section for your review. The debugging option will automatically disable after 48 hours.
- When API tracking is turned off, no logs are saved in the API log.
- Using API Log for Troubleshooting: The API log provides detailed information on all API calls made to Callgoose SQIBS. You can check the JSON values in each API log entry for troubleshooting purposes. Use the information in the API log to verify if your Lambda function is successfully sending the payload and to refine your API filters.
7. Conclusion
By following this guide, you have successfully integrated the Serverless Framework with Callgoose SQIBS.
This integration ensures your operations team triggers the right response immediately when serverless components fail, significantly reducing Mean Time to Resolve (MTTR). For further assistance or advanced configurations, please refer to the official Callgoose SQIBS support channels.
