Inbound integrations

Alerts have to come from somewhere. OpsPing gives every integration its own webhook URL — the URL is the credential, no API key needed at the sender — and maps payloads from the common monitoring tools automatically. Anything that can POST JSON or send email can page you.

1. Create the integration and copy its webhook URL

   On the Integrations page, create an integration and pick a type — generic, Grafana, Alertmanager, Datadog, CloudWatch/SNS, or email. Each integration gets a unique webhook URL:

   https://api.ops-ping.com/v2/webhooks/inbound/<integrationId>/<token>

   The token is minted on creation and lives in the URL — treat the URL like a password. Anyone who has it can create alerts in your tenant. If it leaks, rotate it from the integration's page (the old URL stops working immediately).

   Note

   One integration per source system. Keeping Grafana and Datadog on separate integrations keeps alert provenance, rate limits, and team scoping clean — each integration can be assigned to a team.

2. Post native JSON directly

   The simplest path: POST an OpsPing alert body. No mapper involved — whatever you send is the alert.

   curl -X POST https://api.ops-ping.com/v2/webhooks/inbound/<id>/<token> \
     -H "Content-Type: application/json" \
     -d '{"message":"Payments API error rate 12%","priority":"P1","alias":"payments-errors","tags":["payments"],"description":"5xx spike since deploy 4471"}'

   Fields: message (required), priority P1–P5, alias, tags, entity, description, and a free-form details object. Creation goes through the same path as the alerts API, so dedupe, routing, alert policies, escalation, and push all behave identically. Rate limit: 300 requests per minute per integration.

3. Use a mapper for your monitoring tool

   Point the tool's webhook at the same URL and OpsPing recognizes the payload shape. Detection is automatic — you rarely need to set the type explicitly.

   • Grafana — the Grafana alerting webhook sends { "alerts": [...] }, the same shape as Alertmanager. Each entry maps labels.alertname → message, labels.severity → P1–P5, and the alert's fingerprint → alias. The Grafana externalURL is carried into details so the alert links back to the panel.
   • Prometheus Alertmanager — v4 webhook payloads, same alerts array. alertname → message, severity maps critical/​error/​warning/​info/​debug to P1–P5 (missing or unknown → P3), fingerprint → alias. resolved entries close the matching alert; labels and annotations land in details.
   • CloudWatch via SNS — point the SNS topic's HTTPS subscription at the webhook URL. The SNS envelope is unwrapped automatically; ALARM state creates an alert (alias cloudwatch:<AlarmName>, P3, reason as description) and OK state closes the open alert for that alarm. INSUFFICIENT_DATA and SNS subscription-confirmation messages are handled and ignored — no noise.
   • Datadog — the monitor webhook: title → message, body → description, alert_id → alias (datadog-<id>), alert_type → priority. A Recovered transition closes the alert the earlier Triggered one opened.
   • Generic — any other JSON with a message field goes through as a native alert. Everything else in the payload is ignored, so a shell script with curl is a fully supported integration.

   When a payload contains multiple alerts (Grafana and Alertmanager send arrays), each entry is processed individually and the response tallies the outcomes: { "result": "processed", "created": 2, "deduped": 1, "closed": 1, ... }.

   Tip

   The alias is what makes the loop close. Firing creates an alert with alias X; resolved/OK/Recovered closes whatever alert currently owns alias X — even if it's already been acknowledged. Give your monitors stable identifiers (fingerprints, alarm names, monitor IDs) and open-and-close just works.

   Note

   Dedupe is alias-based: if an alert with the same alias is already open, a new firing for it is counted as a duplicate instead of creating a second alert — the counter increments, nobody gets paged twice. Send the alias from your source tool when you can; it costs one field and buys dedupe plus auto-close.

4. Page by email

   For tools that can only send mail — legacy monitors, cron jobs, a colleague's script — each integration gets an inbound email address:

   <integrationId>.<token>@alerts.ops-ping.com

   Copy it from the integration's page. Any mail sent to it becomes an alert: the subject line is the message (minus the priority tag), the body becomes the description, and the sender is recorded in details. Set priority with a tag in the subject:

   Subject: [P2] Nightly ETL failed on step 3

   [P1]–[P5] are recognized; no tag means P3. Email is create-only — there's no resolve-by-reply, so use the webhook mappers for open/close loops and email for one-way pings.

   Note

   Emails are deduplicated by their Message-ID header — the same message delivered or forwarded twice creates one alert, not two. Monitoring systems that reuse a Message-ID across distinct incidents would collide; if yours does that, send distinct IDs or use the webhook instead.

5. Mind maintenance windows

   Inbound alerts respect maintenance windows like any other alert. If a window is active for the service or team the integration feeds, alerts that arrive during it are suppressed — the webhook still answers 202, so your monitoring tool won't retry or escalate on its own, but nothing pages and nothing pollutes your stats. The alert activity trail records the suppression, so you can see after the fact what came in during the window.

   Warning

   Suppression is not queueing. An alert suppressed by a maintenance window is gone — it will not page when the window ends. If a real outage starts during planned maintenance, the monitoring tool's next evaluation (a new firing, a new email) will page, but a single suppressed event won't. Scope windows tightly.