> ## Documentation Index
> Fetch the complete documentation index at: https://docs.obsy.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Route alerts from Datadog, Grafana, and New Relic into Obsy.

Obsy provides a unique per-organization webhook URL for each supported monitoring platform. When an alert fires, the platform POSTs to your URL, and Obsy normalizes it into an Alert entity, runs RCA, and optionally creates an incident.

***

## Your webhook URLs

Go to **OTel Collector → Create Monitors** to see your URLs, or fetch them directly:

```
GET /api/v1/webhooks/urls
Authorization: Bearer {token}
```

Response:

```json theme={null}
{
  "datadog":  "https://api.obsy.ai/api/v1/webhooks/{orgId}/datadog",
  "grafana":  "https://api.obsy.ai/api/v1/webhooks/{orgId}/grafana",
  "newrelic": "https://api.obsy.ai/api/v1/webhooks/{orgId}/newrelic"
}
```

***

## Platform setup

| Platform  | Where to configure                                         | Format                     |
| --------- | ---------------------------------------------------------- | -------------------------- |
| Datadog   | Integrations → Webhooks → New → URL: `{datadog URL}`       | Datadog monitor payload    |
| Grafana   | Alerting → Contact points → Webhook → URL: `{grafana URL}` | AlertManager JSON          |
| New Relic | Alerts → Destinations → Webhook → URL: `{newrelic URL}`    | New Relic Workflow payload |

Detailed steps: [Datadog alerts](/alerts/datadog) · [Grafana alerts](/alerts/grafana) · [New Relic alerts](/alerts/newrelic)

***

## What happens when a webhook arrives

1. **Parse** — payload is normalized to a common Alert format (service, severity, signal type, labels)
2. **Store** — Alert is saved with a link to the raw payload for debugging
3. **RCA** — if severity is critical, an AI analysis starts in the background
4. **Auto-incident** — if an auto-create rule matches, an incident is created
5. **Slack** — if an incident is created and Slack is configured, a channel is opened and notifications are sent

***

## Security

Webhook endpoints are **public URLs** authenticated by the `{orgId}` in the path. The org ID is a UUID — it cannot be guessed. If you need additional security:

* **Datadog**: configure a webhook secret in Datadog's webhook settings and validate it in your pipeline (Obsy logs but does not reject unsigned Datadog webhooks by default).
* **Grafana / New Relic**: no signing support at this time — rely on the org ID as the secret.

***

## Generic webhook (custom integrations)

For tools not listed above, use the generic endpoint:

```
POST /api/v1/webhooks/alerts
```

Payload:

```json theme={null}
{
  "organization_id": "{orgId}",
  "service_name": "my-service",
  "environment": "production",
  "alert_name": "High error rate",
  "description": "Error rate exceeded 5%",
  "severity": "critical",
  "status": "firing",
  "source": "custom",
  "signal_type": "errors",
  "triggered_at": "2026-01-15T14:32:00Z",
  "labels": { "team": "platform" },
  "annotations": { "runbook": "https://wiki.example.com/runbooks/errors" }
}
```

The `source` field accepts: `datadog`, `grafana`, `prometheus`, `otel`, `custom`.