Integration Setup

Integration Setup

Overwatch receives alerts from your monitoring platforms through webhooks. Each integration creates a unique webhook URL that your monitoring tool sends alerts to. Overwatch normalizes incoming payloads into a standard format regardless of the source platform.

How Integrations Work

The integration architecture has four components:

1. Webhook URL: A unique HTTPS endpoint generated for each integration
2. Alert Parser: Platform-specific logic that extracts structured data from the incoming payload
3. Data Transformer: Converts parsed data into Overwatch’s standard alert format
4. Incident Creator: Optionally creates or updates incidents based on alert rules

When a monitoring platform sends a webhook, the request flows through these components in sequence. The result is a normalized alert record linked to your organization.

General Setup Flow

Step 1: Create the Integration in Overwatch

1. Log in to the Overwatch dashboard
2. Navigate to Settings > Integrations
3. Click Add Integration
4. Select your monitoring platform from the list
5. Give the integration a name (e.g., “Datadog Production” or “Grafana Staging”)
6. Click Create

Overwatch generates a webhook URL. Copy this URL — you will configure it in your monitoring platform in the next step.

Note: Each integration has its own webhook URL. If you monitor multiple environments (production, staging), create a separate integration for each one. This keeps alerts organized and allows different alert routing rules per environment.

Step 2: Configure Your Monitoring Platform

Add the Overwatch webhook URL to your monitoring platform’s notification or webhook configuration. The exact steps differ by platform; see the platform-specific sections below.

Step 3: Send a Test Alert

Trigger a test alert from your monitoring platform to verify the integration. Most platforms provide a “Test Notification” or “Send Test” button in their webhook configuration.

Step 4: Verify in Overwatch

Return to the Overwatch dashboard and check:

1. Settings > Integrations: The integration status should show Connected with a recent “last received” timestamp
2. Incidents page: If auto-creation is enabled, a test incident should appear
3. Activity feed: The webhook delivery should appear in the activity log

Platform-Specific Configuration

Datadog

1. In Datadog, go to Integrations > Webhooks (or Monitors > Notifications)
2. Click New Webhook
3. Set the URL to your Overwatch webhook URL
4. Leave the payload as the default JSON format — Overwatch’s Datadog parser handles the standard payload
5. Under Custom Headers, add:

   Content-Type: application/json

6. Save the webhook
7. Edit any monitors that should send alerts to Overwatch and add the webhook as a notification channel using @webhook-overwatch

Tip: Datadog sends different payloads for metric monitors, log monitors, and composite monitors. Overwatch handles all three types. For the richest context, use metric monitors with the “Include triggering tags” option enabled.

Grafana

1. In Grafana, go to Alerting > Contact Points
2. Click Add Contact Point
3. Select Webhook as the type
4. Set the URL to your Overwatch webhook URL
5. Set HTTP Method to POST
6. Save the contact point
7. Create or edit a Notification Policy to route alerts to this contact point

For Grafana Cloud, the process is the same. For self-hosted Grafana, ensure the Grafana server can reach the Overwatch webhook URL over HTTPS.

PagerDuty

1. In PagerDuty, go to Services > Service Directory
2. Select the service you want to integrate (or create a new one)
3. Go to the Integrations tab and click Add Integration
4. Select Generic Webhook (V3)
5. Set the Endpoint URL to your Overwatch webhook URL
6. Save the integration

PagerDuty sends webhooks for incident creation, acknowledgment, resolution, and escalation. Overwatch processes all event types to keep incident status synchronized.

Other Platforms

Overwatch also supports webhooks from:

• Prometheus Alertmanager: Configure a webhook receiver in your alertmanager.yml pointing to the Overwatch URL
• New Relic: Add a webhook notification channel under Alerts > Notification Channels
• SigNoz: Configure webhook alerts in Alerts > Notification Channels
• Elasticsearch/OpenSearch: Use Watcher or Alerting plugin to send webhook actions
• AWS CloudWatch: Use an SNS topic with an HTTPS subscription pointing to the Overwatch URL

Testing and Validation

After setting up an integration, verify it works end to end:

1. Trigger a real alert: Create a condition that fires your monitor (e.g., set a low threshold temporarily)
2. Check webhook delivery: Most platforms show delivery status and response codes in their webhook logs
3. Verify parsing: Open the resulting alert or incident in Overwatch and confirm all fields (title, severity, service, tags) were parsed correctly
4. Test resolution: Resolve the alert in your monitoring platform and verify Overwatch updates the incident status

Tip: Keep your monitoring platform’s webhook delivery log open during testing. A 200 response from Overwatch means the webhook was received and parsed successfully. A 400 response indicates a payload parsing error — check the integration logs in Overwatch for details.

Troubleshooting

Webhook Not Received

• Confirm the webhook URL is correct (no trailing spaces or missing path segments)
• Check that your monitoring platform can reach api.overwatch-observability.com over HTTPS (port 443)
• Verify there are no firewall rules, proxy configurations, or IP allowlists blocking outbound traffic
• Check the monitoring platform’s webhook delivery logs for HTTP errors or timeouts

Authentication Errors (401/403)

• Each webhook URL contains an embedded authentication token. If you regenerate the integration in Overwatch, you must update the URL in your monitoring platform
• Verify the integration has not been deleted or disabled in Overwatch

Alerts Received But Not Parsed Correctly

• Confirm you selected the correct platform type when creating the integration
• Check that your monitoring platform is sending the default payload format (custom payload templates may not parse correctly)
• Review the raw webhook payload in Settings > Integrations > [Integration Name] > Recent Deliveries

Duplicate Alerts

• Some platforms send multiple webhooks for the same event (e.g., state changes and re-notifications). Overwatch deduplicates by alert ID when possible
• If you see duplicates, check your monitoring platform’s notification rules for redundant webhook triggers

Next Steps

• Incident Response Workflow — Use your integrations during live incident response
• Creating Procedures — Build runbooks triggered by specific alert types
• Platform-specific guides — Detailed configuration for each supported platform