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.
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.alertnameandannotations.summarymake 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
alertsarray) and the older single-alert body are both understood.Generic JSON.
{"title": "Site down", "key": "pingdom-1", "severity": "p1", "detail": "…", "status": "firing"};statusresolved(orok,resolve,recovered) closes it. A list underalertssends 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.