---
title: Alert sources
description: "Point Prometheus Alertmanager, Grafana or any JSON sender at a signed URL to page the on-call and, if you want, open an incident."
section: incidents
order: 17
audience: [user, operator, agent]
sources: [services/nodejs-cloud/lib/incidents/inbound.ts, services/nodejs-cloud/lib/incidents/sources.ts, services/nodejs-cloud/lib/integrations/inbound/verify.ts, services/nodejs-cloud/app/incidents/api/v1/inbound, services/nodejs-cloud/migrations/0160_oncall.sql, docs/adr/0055-venom-incidents.md]
features: []
---

An alert source is a URL with a secret. Alerts your monitoring already produces arrive there, page the on-call, and can
open an incident. It is inbound only: Venom Cloud does not call your monitoring.

Create one in **On-call, Alert sources, New source** (an owner or admin). Pick the kind, the escalation policy to page (the
default one if you leave it), and whether a firing alert also opens an incident (a severity, or only page). The
secret is shown once; copy it. The URL is `https://<your cloud>/incidents/api/v1/inbound/<source id>`.

## Authenticating

Send the secret one of two ways. Both are checked in constant time against the raw body.

| How | Header |
|---|---|
| Bearer token | `Authorization: Bearer <secret>` |
| Signature | `X-Venom-Signature: sha256=<hex HMAC-SHA256 of the body, keyed with the secret>` (also accepted as `X-Hub-Signature-256`) |

A signed request may add `X-Venom-Timestamp` (unix seconds); then the signature covers `<timestamp>.<body>` and the
timestamp must be within five minutes, so a captured request cannot be replayed later. An unknown source and a wrong
secret both answer `401`. A source turned off answers `403`.

## Kinds

- **Alertmanager.** A webhook receiver:

  ```yaml
  receivers:
    - name: venom
      webhook_configs:
        - url: https://<your cloud>/incidents/api/v1/inbound/<source id>
          send_resolved: true
          http_config:
            authorization:
              credentials: <secret>
  ```

  Each alert is keyed by its fingerprint. `labels.alertname` and `annotations.summary` make the title; `labels.severity`
  (`critical`, `warning`, `info`, `sev1`, `p2`…) sets the severity.
- **Grafana.** A webhook contact point with the same URL and an Authorization header. Unified alerting (the `alerts`
  array) and the older single-alert body are both understood.
- **Generic JSON.** `{"title": "Site down", "key": "pingdom-1", "severity": "p1", "detail": "…", "status": "firing"}`;
  `status` `resolved` (or `ok`, `resolve`, `recovered`) closes it. A list under `alerts` sends several.

## What happens

A **firing** alert pages the policy. The same alert again (same key) is the same page and only counts up. A **resolved**
alert resolves its page. If the source opens incidents, a new page also declares one at that severity, or worse if the
alert's own severity is worse, in the source's project and environment, and links the page to it. The response is `202` with
`{accepted, paged, repeated, resolved, incidents}`.

See [On-call](/docs/incidents/on-call.md) for what a page does next.
