Firefly

Overview

This document describes how to integrate Firefly notifications with Callgoose SQIBS using Firefly's Webhook integration. The integration sends Firefly event notifications (drift detection, policy violations, ClickOps events, workspace run status, and more) as JSON webhook payloads to Callgoose, where API Filters convert them into incidents that can be created and auto-resolved.

Prerequisites

• A Firefly account with permissions to configure Settings → Integrations and manage Notifications.
• A Callgoose SQIBS account with permission to create API Tokens and API Filters.
• A reachable HTTPS endpoint for Callgoose (your Callgoose API Endpoint + token).
• (Optional) Any custom credentials you intend Firefly to use when calling your endpoint.

1. Install Firefly

Firefly is a hosted SaaS platform. No local installation is required for webhook-based integrations. All steps for integration are performed using the Firefly UI.

1.1. Install using Helm / YAML / Docker

Not applicable. Firefly does not require local installation for webhook integrations. All configuration is done through the UI.

2. Obtain the Callgoose SQIBS Webhook URL

• In Callgoose SQIBS: generate or locate the API Endpoint used to receive incoming events.
• Copy the full endpoint including the token parameter. This will be used as the destination URL inside Firefly.

3. Create the Firefly → Callgoose Webhook Integration

• In Firefly, open Settings → Integrations.
• Select Add New → Webhook Integration.
• Enter a descriptive Nickname.
• Paste the Callgoose webhook URL.
• (Optional) Add authentication or custom headers if required by your endpoint.
• Save the integration.
• Use the Test button to verify that Firefly can deliver events to Callgoose.

4. Define Notification Rules in Firefly

• Open Notifications inside Firefly.
• Click Add new to create a new notification rule.
• Select the Event Type such as Drift Detection, Policy Violation, ClickOps Event, Workspace Run, or Guardrail Violation.
• Add filtering criteria (provider, resource type, tags, owners, regions, etc.).
• Set Destination as the webhook integration you created earlier.
• Save and enable the rule.

5. Example Firefly Webhook Payloads

5.1. Example Payload (Drift Event)

{
  "accountId": "acc-12345",
  "accountName": "production-aws",
  "assetType": "ec2-instance",
  "integrationId": "intg-9876",
  "integrationIdentifier": "aws-us-east-1",
  "integrationName": "AWS Inventory Crawler",
  "notificationType": "Drift",
  "providerType": "aws",
  "region": "us-east-1",
  "samples": [
    {
      "ARN": "arn:aws:ec2:us-east-1:123456789012:instance/i-0abcd",
      "FRN": "frn:example",
      "crawlerId": "crawler-1",
      "drifts": [
        {
          "iacType": "terraform",
          "iacValue": "resource \"aws_instance\" \"web\" { ... }",
          "keyName": "instance_type",
          "providerValue": "t3.large"
        }
      ],
      "firstSeen": "2025-10-01T12:05:00Z",
      "inventoryUpdateTime": "2025-10-01T12:00:00Z",
      "name": "web-01",
      "ownerData": { "ActionType": "Modify", "eventTime": "2025-10-01T11:59:58Z" }
    }
  ],
  "workflowId": "wf-42"
}

6. Configure API Filters in Callgoose SQIBS

6.1. Trigger Filter — Create Incident

• Payload Key: "notificationType"
• Value Contains: Drift
• Map Incident With: "samples".[0]."ARN" or "accountId"
• Incident Title: combine fields such as "samples".[0]."name"
• Description: map to any field or leave blank to include full payload

6.2. Resolve Filter — Auto-Resolve Incident

If Firefly provides a resolved state for an event type:

• Payload Key: the appropriate field (e.g., notificationType or a status field)
• Value Contains: resolved state
• Map Incident With: same key used in Trigger Filter

If Firefly does not provide a resolution event, configure time-based auto-resolution in Callgoose. Refer to the API Filter Instructions and FAQ for more details.

7. Testing the Integration

• Use Firefly’s Test button to send a sample payload.
• Verify that Callgoose receives and logs the payload.
• Create a test event in Firefly matching your notification rule.
• Confirm:
• Incident creation in Callgoose
• Correct correlation and mapping
• Trigger a clearing event if supported to confirm auto-resolve.

8. Troubleshooting

• No Payload Received
• Verify webhook URL and token.
• Ensure the integration is enabled.
• Check that Callgoose returns a 200 response.
• Field Mapping Incorrect
• Inspect actual payload in Callgoose logs.
• Adjust JSON keys and nesting in API Filters.
• Incidents Not Resolving
• Confirm Firefly emits a resolved notification for the event type.
• Otherwise configure a fallback resolution strategy.
• Authentication Issues
• Ensure any credentials configured in Firefly match what Callgoose expects.

9. Security Considerations

• Always use HTTPS endpoints.
• Keep tokens secret and rotate periodically.
• Restrict permissions to minimum required.
• Avoid embedding sensitive data in code repositories.

10. Conclusion

Integrating Firefly with Callgoose SQIBS using webhook notifications automates incident creation for drift, policy violations, ClickOps activity, and workspace events. By configuring targeted notification rules in Firefly and mapping their payloads using Callgoose API Filters, teams can maintain real-time visibility and quickly respond to important changes.

For further customization or advanced use cases, refer to the official documentation for both Firefly and Callgoose SQIBS:

• Firefly Documentation
• Callgoose SQIBS API Token Documentation
• Callgoose SQIBS API Endpoint Documentation
• API Filter Instructions and FAQ
• How to Send API