obkio

Overview

This guide details the process for integrating Obkio Webhooks with Callgoose SQIBS to enable real-time Incident Management and automated network-performance alert workflows. The integration uses Obkio Webhooks to send alert payloads (latency, packet loss, jitter, agent availability) directly to the Callgoose API endpoint. Callgoose API Filters then automatically create and resolve incidents based on the alert status.

Prerequisites

• A Callgoose SQIBS account with API Filters access.
• Obkio Cloud subscription or a running on-prem deployment.
• A valid Callgoose API token and Api endpoint URL.
• At least one configured Obkio Alert Rule to test incident behavior.

For Local Deployments

• Outbound internet access is required for webhook delivery to a Cloud-hosted Callgoose SQIBS.
• Ensure DNS Resolution for callgoose.com is correct.
• Firewall Rules must allow outbound HTTPS (TCP 443) traffic.

1. Prepare Callgoose: Obtain Endpoint and Token

1.1 Retrieve Callgoose API Endpoint

Use the Callgoose process endpoint with token authentication:

https://****.callgoose.com/v1/process?from=obkio&token=xxxx

Keep the API token private and never store it in exposed configuration sources.

2. Configure Obkio Webhook

2.1Configure Obkio Webhook (Cloud Deployment)

Navigate to Organization → Advanced Parameters → Webhooks.

Enter the following details:

• Webhook Type: Obkio Webhook
• Webhook URL: The Callgoose endpoint from Step 1.
• Method: POST
• Body Format: json
• Send Recovery Events: Enabled (Required for auto-resolve functionality)

Save & Enable the webhook.

2.2Configure Obkio Webhook (Self-Hosted / Local Deployment)

Navigate to Admin Portal → Webhooks → Add Webhook Notification.

enter the following details:

• HTTP Method → POST
• Content Type → application/json
• Webhook URL → The Callgoose Process Endpoint: https://****.callgoose.com/v1/process?from=Obkio&token=xxxx

For Fully Air-Gapped / Offline Environments: You must deploy a local Callgoose instance and use an internal API Endpoint (e.g., https://callgoose-internal.company.local/v1/process?from=Obkio&token=xxxx) or configure an approved egress proxy for outbound routing.

3. Obkio Webhook Payload Structure

Obkio sends a standardized JSON envelope containing the alert data under the "data" field.

Alert Firing (Problem Detected) Example

JSON

{
  "type": "notification.triggered",
  "created": 1670153085,
  "data": {
    "status": "firing",
    "alert_id": "obkio-alert-87426",
    "alert_name": "Packet Loss High",
    "description": "Packet loss above 10% detected",
    "severity": "critical",
    "timestamp": "2025-12-03T14:04:45Z",
    "metrics": {
      "packet_loss_pct": 14.2
    },
    "agents": {
      "source": "HQ-EDGE",
      "destination": "DC-GW"
    }
  }
}

Alert Resolve (Condition Normal) Example

JSON

{
  "type": "notification.resolved",
  "created": 1670153310,
  "data": {
    "status": "resolved",
    "alert_id": "obkio-alert-87426",
    "timestamp": "2025-12-03T14:08:30Z"
  }
}

4. Create API Filters in Callgoose SQIBS

The API filters must reference the keys inside the "data" object of the Obkio payload.

4.1 Trigger Filter — Create Incident

This filter creates a new incident when the Obkio alert condition is met.

• Payload JSON Key: "data"."status"
• Key Value Contains: firing
• Map Incident With: "data"."alert_id "(Ensures the incident can be resolved later)
• Incident Title: "data"."alert_name"
• Incident Description:" data"."description"

4.2 Resolve Filter — Auto-Resolve Incident

This filter automatically resolves the corresponding incident in Callgoose when the Obkio alert condition returns to normal.

• Payload JSON Key: "data"."status"
• Key Value Contains: resolved
• Incident Mapped With: "data"."alert_id "(Must match the key used for creation)

Refer to the API Filter Instructions and FAQ for more details.

5. Verify and Test Integration

Perform the following steps to ensure bidirectional communication and incident automation are functioning correctly.

• Trigger Test Webhook: Use the built-in test feature in Obkio (available in both Cloud & Local deployments).
• Confirm API Logs in Callgoose: Check the API logs to ensure the webhook payload is successfully received and processed by Callgoose.
• Check Incident Creation: Verify that a new incident is created in Callgoose when an Obkio alert fires.
• Confirm Auto-Resolve: Verify that the corresponding incident in Callgoose automatically resolves when the Obkio alert status returns to normal.

6.Troubleshooting

This section provides common issues and detailed verification steps to diagnose problems with the Obkio Webhook and Callgoose API Filters integration.

6.1 No Payload Received in Callgoose

• Check Network Path: Verify that the Firewall Rules allow outbound HTTPS (TCP 443) traffic from the Obkio host (especially for on-premise deployments) to the Callgoose API endpoint (https://****.callgoose.com).If a proxy is in use, ensure the Obkio configuration correctly includes the proxy settings for outbound webhooks.
• Review Obkio Logs: Check the Obkio agent or appliance logs for any specific error messages related to the webhook delivery (e.g., connection timed out, DNS failure).
• Verify Webhook URL: Ensure the Webhook URL in Obkio is an exact match for the Callgoose process endpoint, including the correct ?from=Obkio&token=xxxx parameters.

6.2 Incidents Not Resolving Automatically

• Obkio Recovery Events: In the Obkio Webhook settings, confirm that "Send Recovery Events" is Enabled. This is essential for Obkio to send the "resolved" payload.
• Payload Verification: Ensure the Obkio resolve payload includes "status": "resolved".
• Callgoose Resolve Filter: Verify the Resolve Filter in Callgoose SQIBS:
• Payload JSON Key: Must be set to data.status.
• Key Value Contains: Must be set to resolved.
• Incident Mapped With: Must be set to data.alert_id.

6.3 Wrong Incident Title or Description

• Check API Filter Mappings: The mapping fields in the Callgoose Trigger Filter must match the corrected Obkio payload structure:
• Incident Title: Set to data.alert_name.
• Incident Description: Set to data.description.

6.4 Duplicate Incidents Being Created

• Consistency is Key:
• Ensure the mapping key used for incident creation and the key used for resolution are identical.
• In the Callgoose Trigger Filter (Create Incident), "Map Incident With" must be set to data.alert_id.
• In the Callgoose Resolve Filter (Auto-Resolve Incident), "Incident Mapped With" must also be set to data.alert_id. The unique alert_id ensures the correct incident is updated.

7.Conclusion

Integrating Obkio with Callgoose SQIBS establishes a robust, automated pipeline for network incident management, providing instant incident creation on network performance degradation and automatic closure when metrics recover. This centralized visibility ensures operational reliability for critical network links.

For further customization or advanced use cases, refer to:

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