Skip to content
Docs menu

Alert sources

Point Prometheus Alertmanager, Grafana or any JSON sender at a signed URL to page the on-call and, if you want, open an incident.

View .md

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:

    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 for what a page does next.