Integrations
Blackfire.io
Overview
This document provides a detailed guide to integrating Blackfire.io 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 alerts generated in Blackfire Monitoring.
This guide explains how to configure Blackfire Webhooks, define JSON payloads, create API filters in Callgoose SQIBS, test the flow, and troubleshoot the integration.
Prerequisites
Before beginning, ensure you have:
- A Blackfire.io account with access to Monitoring, Environments, and Alerting.
- A Callgoose SQIBS account with permission to create API filters.
- A Callgoose Webhook/API Endpoint generated from the Callgoose console.
- A valid Callgoose API Token.
- Network access that allows Blackfire Monitoring to POST alert data to the Callgoose endpoint.
1. Obtain API Token and Endpoint Details (Callgoose SQIBS)
1.1 Generate an API Token
Create an API token from Callgoose SQIBS. Save it securely.
1.2 Find or Construct the Webhook Endpoint
Your Callgoose webhook endpoint follows this pattern:
https://****.callgoose.com/v1/process?from=Blackfire&token=<API_TOKEN>
Replace <API_TOKEN> with your correct values.
The from parameter helps identify Blackfire events inside Callgoose logs.
2. Configuring Blackfire.io to Send Alerts
Blackfire Monitoring provides alerting capabilities for performance regressions, threshold breaches, error rate spikes, and custom metrics.
You will configure a Webhook Notification Channel so Blackfire can send alert events to Callgoose.
2.1 Open Blackfire Monitoring Settings
In Blackfire:
- Navigate to the relevant Environment.
- Open Monitoring.
- Go to Alerts.
- Choose Add Alert or edit an existing alert.
2.2 Create a Webhook Notification Channel
Inside the alert configuration:
- Select Webhook as the notification method.
- Configure the following:
- Name:
- Callgoose SQIBS Webhook
- URL:
- The Callgoose endpoint from Section 1.2
- Method:
- POST
- Content Type:
- application/json
Blackfire supports variable injection inside webhook payloads. You will define a structured JSON body next.
2.3 Define the JSON Payload Template
Use a clean, predictable JSON structure.
Below is the recommended Blackfire Monitoring webhook payload structure:
{
"alert_id": "{{ alert.uuid }}",
"state": "{{ alert.state }}",
"severity": "{{ alert.severity }}",
"title": "{{ alert.title }}",
"description": "{{ alert.description }}",
"metric_name": "{{ alert.metric_name }}",
"metric_value": "{{ alert.metric_value }}",
"threshold": "{{ alert.threshold }}",
"environment": "{{ environment.name }}",
"application": "{{ application.name }}",
"timestamp": "{{ alert.timestamp }}"
}
The available placeholders may vary depending on your Blackfire plan and version.
Ensure the values match the supported Blackfire variables in your environment.
2.4 Attach Webhook to Alerts
- Save your Webhook configuration.
- Add it to any Alert Rule you want to forward to Callgoose.
2.5 Test Webhook Delivery
Blackfire provides a Test Notification button.
Use this to verify the webhook can reach Callgoose successfully.
3. Example JSON Payloads from Blackfire.io
3.1 Triggered Alert Payload
When a performance regression or metric breach occurs:
{
"alert_id": "bf-alert-98234",
"state": "triggered",
"severity": "critical",
"title": "High Response Time Detected",
"description": "Response time exceeded 2500ms",
"metric_name": "response_time",
"metric_value": "2800",
"threshold": "2500",
"environment": "Production",
"application": "Checkout-Service",
"timestamp": "2025-02-12T14:12:45Z"
}
3.2 Resolved Alert Payload
When the condition returns to normal:
{
"alert_id": "bf-alert-98234",
"state": "resolved",
"severity": "info",
"title": "Response Time Normalized",
"description": "Performance returned to acceptable levels.",
"environment": "Production",
"application": "Checkout-Service",
"timestamp": "2025-02-12T14:18:22Z"
}
4. Configuring Callgoose SQIBS
4.1 Create API Filters
Callgoose API Filters match incoming JSON keys and convert Blackfire events into incidents.
4.1.1 Trigger Filter (Create Incidents)
Configure:
- Payload JSON Key: "state"
- Key Value Contains: triggered
- Map Incident With: "alert_id"
- Incident Title: "title"
- Incident Description: "description" (or leave empty to recieve full payload)
This ensures an incident is created for each new Blackfire alert.
4.1.2 Resolve Filter (Auto-Resolving Incidents)
Configure:
- Payload JSON Key: "state"
- Key Value Contains: resolved
- Incident Mapped With: "alert_id"
This resolves the correct incident automatically. Refer to the API Filter Instructions and FAQ for more details.
5. Testing & Validation
5.1 Triggering Alerts in Blackfire
- Temporarily reduce an alert threshold.
- Force a performance spike on the monitored application.
- Confirm Callgoose receives the alert and creates an incident.
5.2 Resolving Alerts
- Restore performance conditions to normal.
- Blackfire sends a resolved webhook.
- Confirm incident auto-resolves in Callgoose.
6. Debugging & Troubleshooting
- No Incident Created
- Verify webhook URL and token.
- Ensure JSON key state contains triggered.
- Confirm Blackfire webhook test returns HTTP 200.
- Incident Not Resolving
- Ensure the alert_id matches between triggered and resolved events.
- Check the Resolve Filter condition equals resolved.
- Malformed JSON
- Ensure Blackfire placeholders used in the payload template are supported.
- Validate JSON syntax before saving.
- Authentication Failures
- Regenerate Callgoose token if necessary.
- Ensure no extra characters were added to the endpoint.
7. Security Considerations
- Keep API tokens private.
- Use HTTPS for all webhook transmissions.
- Rotate Callgoose tokens periodically.
- Restrict Blackfire outbound webhook traffic if using firewalls.
8. Conclusion
By following this guide, you can successfully integrate Blackfire.io Monitoring with Callgoose SQIBS, enabling automated incident creation, performance anomaly visibility, and rapid resolution workflows.
This ensures your engineering, DevOps, and SRE teams gain real-time performance insights directly within Callgoose's incident management pipeline.
For further customization or advanced use cases, refer to the official documentation for both Blackfire and Callgoose SQIBS:
