papertrail

Overview

This document provides a detailed guide to integrating Papertrail with Callgoose SQIBS for real-time Incident Management, log-based alerting, and automated incident resolution.

The integration uses Papertrail Webhooks to send alert event payloads directly to Callgoose, where API Filters convert them into incidents that are automatically created and resolved.

Prerequisites

Before beginning, ensure you have the following:

• A Callgoose SQIBS account with permissions to create API Filters and access the integration endpoint
• A Papertrail account with access to create Alerts and Webhooks
• A valid Callgoose API token and Api endpoint URL.
• A test Papertrail alert (recommended) for validating webhook delivery and payloads

1. Prepare Callgoose: Obtain Endpoint and Token

1.1 Retrieve Callgoose API Endpoint

Generate or locate your Callgoose process endpoint:

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

• Store the API token securely
• Never commit the token to source control

2. Configure Papertrail Webhook

2.1 Create or Select an Alert

In Papertrail:

• Go to Settings → Alerts
• Create a New Alert or edit an existing one
• Define the log query and alert threshold (e.g., error count, matching pattern)

Papertrail alerts are log-query based and trigger when the defined condition is met.

2.2 Configure Webhook Destination

In the alert configuration:

• Enable Webhook Notifications
• Set the following fields:

Webhook URL

• Callgoose endpoint from Step 1

HTTP Method

• POST

Content Type

• application/json

Send Recovery Notification

• Must be Enabled to allow auto-resolution in Callgoose

Save and enable the alert.

2.3 Webhook Event Behavior

Papertrail sends webhook events for:

• Alert Triggered (threshold breached)
• Alert Recovered (condition cleared)

These events are used by Callgoose to create and resolve incidents automatically.

3. Example Papertrail Payloads

A simplified Papertrail alert-triggered payload:

{"event": "alert.triggered","alert": {"id": 98231,"name": "High Error Logs","query": "level:error","severity": "critical"},"triggered_at": "2025-10-01T12:05:00Z","count": 124,"source": "papertrail"
}

Recovered (resolved) event example:

{"event": "alert.recovered","alert": {"id": 98231,"name": "High Error Logs"},"recovered_at": "2025-10-01T12:18:40Z","source": "papertrail"
}

always inspect your actual payloads inside Callgoose API Logs and use those exact fields in your API Filter mappings.

4. Create API Filters in Callgoose SQIBS

Callgoose API Filters convert incoming Papertrail webhooks into incidents.

Use two filters:

• Trigger Filter (create incident)
• Resolve Filter (auto-resolve incident)

4.1 Trigger Filter — Create Incident

Use the following settings:

• Payload JSON Key: event
• Key Value Contains: alert.triggered
• Map Incident With: alert.id
• Incident Title: alert.name
• Incident Description:
• Optional — leave empty to store full JSON payload

This filter creates an incident whenever a Papertrail alert fires.

4.2 Resolve Filter — Auto-Resolve Incident

Use the following settings:

• Payload JSON Key: event
• Key Value Contains: alert.recovered
• Incident Mapped With: alert.id

This ensures the incident is resolved when the Papertrail alert recovers.

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

5. Verify and Test the Integration

5.1 Test Initial Delivery

• Create a broad test filter in Callgoose
• Trigger the Papertrail alert condition
• Confirm Callgoose receives the payload in API Logs

5.2 View Exact Payload

• Open Callgoose → API Request Logs
• Inspect the full JSON payload sent by Papertrail
• Copy field names directly for accurate filter configuration

5.3 Final Verification

• Trigger alert in Papertrail → Incident should be created in Callgoose
• Clear alert condition → Incident should auto-resolve
• Confirm mapping consistency using alert.id

6. Troubleshooting

Incoming Payload Not Received

• Check Papertrail alert webhook configuration
• Verify endpoint URL and API token
• Confirm HTTPS connectivity
• Review Callgoose API logs

Incidents Not Auto-Resolving

• Ensure Recovery notifications are enabled in Papertrail
• Confirm alert.recovered event is sent
• Verify the same alert.id is used for trigger and resolve

Wrong or Missing Payload Fields

• Inspect webhook payloads in Callgoose API logs
• Update API Filters to match exact JSON structure
• Re-test using triggered + recovered conditions

7. Conclusion

Integrating Papertrail with Callgoose SQIBS enables automated incident creation and resolution directly from log-based alerts. By forwarding Papertrail alert events via webhooks and mapping them through Callgoose API Filters, teams gain immediate operational visibility into log anomalies and error spikes.

With properly configured Trigger and Resolve filters, this integration ensures log alerts instantly become actionable incidents—and are automatically closed when the issue is resolved—improving response time and operational reliability.

• OpenObserve Documentation
• Callgoose SQIBS API Token Documentation
• Callgoose SQIBS API Endpoint Documentation
• API Filter Instructions and FAQ