Skip to main content

​
About AlertOps

AlertOps is an incident alerting and on-call management platform. The Serval AlertOps integration connects with a single credential — your AlertOps User API key — and gives workflows typed access to every published AlertOps API surface: the modern v2 REST API, the legacy v1 API, and the inbound alert-ingestion endpoint. Serval attaches your key in the right place for each API family automatically (header, query parameter, or request body), so there is nothing technical to configure beyond pasting the key. Authentication: API key (an AlertOps User API key, from your AlertOps user profile) Data sync: On-demand only. Connecting AlertOps does not import alerts or any other records into Serval, and there are no background syncs — all access happens when a workflow runs an AlertOps action.

​
What the AlertOps integration enables

The v2 and legacy v1 APIs are exposed as two separate typed actions (AlertOps API request and AlertOps legacy v1 API request). Prefer v2 — it is RESTful, accepts names where v1 requires numeric IDs, and covers nearly everything — and reach for v1 only where your account’s tooling depends on it.

​
Get your credentials

1

Open your AlertOps profile

Sign in to AlertOps and click your username in the top-right corner, then select Profile.
2

Copy your API key

Find the API Key section (shown partially masked) and use Copy to copy the full key.
The key is tied to your AlertOps user. Results of user-scoped reads (for example listing alerts with the default “view by user” filter) are relative to that user, and the key carries that user’s permissions. For team automation, use a dedicated service user rather than a personal account.
Regenerate in the profile immediately invalidates the old key. If someone regenerates it, workflows start failing with 401s until you paste the new key into the Serval connection.

​
Connect in Serval

1

Open the AlertOps integration

In Serval, open the AlertOps integration’s connect form.
2

Paste your API key

Paste the User API key into the API Key field (a masked password field).
3

Submit

Submit the form to finish connecting.
When you reopen the connection settings, the stored key is shown obfuscated. Saving the form without changing the field keeps your existing key — you only paste a new value when rotating it.

​
Verifying the connection

The integration ships four health checks, visible on the integration’s settings page:
  1. Test AlertOps Connection — authenticates against the v2 API.
  2. List AlertOps Groups — confirms group read access.
  3. List AlertOps Escalation Policies — confirms escalation-policy read access (needed to create alerts).
  4. List Integrations (Legacy v1 API) — exercises the legacy v1 API’s separate query-parameter auth path.
If the first three pass but the legacy check fails, v2 workflows still work fine — see the gotchas below.

​
Sending alerts into AlertOps

Workflows have two ways to raise an AlertOps alert:
  • Direct (recommended): use the AlertOps API request action with POST /api/v2/alerts, specifying an escalation policy or response play by name. This is fully typed and requires no AlertOps-side setup.
  • Through an inbound integration: use the AlertOps send inbound alert action to POST a payload to https://notify.alertops.com/POSTAlert/{endpointToken}/{source}, exactly as a monitoring tool would. This drives the inbound integration’s field mapping and its “Open / Update / Close Alert When” rules — useful when you want AlertOps-side grouping, delaying, filters, or escalation-policy overrides applied. Create the inbound integration in AlertOps under Configurations → Integrations → Inbound Integrations → + ADD API, then copy the endpoint token (the UUID in the generated URL) and the trailing source segment into the action’s inputs.
Keep the inbound integration’s Method as POST and Content as JSON (both defaults) — the action sends a JSON POST, and AlertOps also offers GET and form-encoded modes that it cannot drive. Nested payload values are fine: map them on the AlertOps side with the caret syntax (issue^id), and array elements as evalMatches_0^metric.
The inbound endpoint URL embeds its own credential (the endpoint token) — treat the token like a secret. Serval deliberately sends no API key to notify.alertops.com. For the same reason, leave the integration’s Authorization Header option off: Serval’s proxy strips Authorization headers from workflow requests, so an inbound integration requiring one cannot be driven from a workflow.

​
Triggering Serval workflows from AlertOps

AlertOps can call Serval when alerts change state (opened, assigned, closed, escalated, SLA thresholds, and any other condition expressible in an AlertOps workflow). This uses Serval’s standard webhook trigger — no integration-specific setup:
1

Create a webhook-triggered workflow in Serval

Give your Serval workflow a Webhook trigger and copy its trigger URL (/v2/webhooks/{webhook_id}/trigger) and secret.
2

Create the outbound call in AlertOps

In AlertOps, either add a Send Webhook action to an AlertOps workflow, or create an Outbound Integration with a REST method. Point it at the Serval trigger URL.
3

Pass the secret

Add the secret as an X-Webhook-Secret header (or a ?secret= query parameter) on the AlertOps side.
4

Shape the payload

Build the JSON body from AlertOps’ dynamic fields (for example <<MessageThread.Topic>>, <<Message.MessageText>>) — whatever you send becomes the workflow’s trigger payload.

​
Gotchas and troubleshooting

The v2 API documents the User API key from your profile. AlertOps’ legacy v1 documentation predates that key and does not state whether older account-level keys differ from it. If only the legacy check fails, your key is valid for v2 but your account’s v1 surface may expect a different key — contact AlertOps support if you need v1, or simply use the v2 equivalents (nearly every v1 endpoint has one).
GET /api/v2/alerts defaults to viewBy=U (alerts visible to the key’s user). Pass viewBy: "A" in the query to list all alerts the account allows, and note its date-range filters (createdFrom/createdTo, closedFrom/closedTo) are capped at six-month windows.
Most v2 list endpoints use integer limit (max 100) and offset with sortBy/sortDir. GET /api/v2/alerts instead uses cursor-style paging: string limit, plus previous/next cursors returned in the response’s metadata envelope.
/api/v2/alerts is the alerting/escalation surface (statuses: Open, Assigned, Closed, On Hold, Cancelled; is_incident flags major-incident management). /api/v2/incidents is the separate status-page surface (Investigating → Resolved) tied to /api/v2/services and subscriber notifications. Don’t conflate them.
AlertOps’ published v2 API spec does not describe response bodies, so v2 actions return untyped JSON (a few legacy v1 read endpoints, like listing topics or schedules, are typed). Consult the response examples in the AlertOps API portal (https://api.alertops.com/help) when mapping fields in your workflow.
AlertOps documents no rate limits. If you build high-volume automation and see 429s or throttling symptoms, add pacing/retries in your workflow design.
Regenerating the API key in an AlertOps profile invalidates the old key instantly. Failed runs with 401 errors after someone touched the profile usually mean exactly this — paste the new key into the Serval connection settings.
The trailing segment of an inbound endpoint URL is the integration’s Source value. Editing Source (or clicking Generate next to the URL) invalidates the old URL the moment the Rules drawer is saved — any workflow still passing the old source segment (or old token) to the send-inbound-alert action starts failing immediately. Update the action’s inputs whenever someone rebrands an inbound integration.
Check the integration’s Inbound Log in AlertOps (Configurations → the inbound integration → Inbound Log) and look at the message’s mapping status. Pending can last up to a minute. Mapping Failed means the Source/Source Name in the URL and payload didn’t match the integration’s mapping fields. Mapped Ignored means the fields mapped but no alert was generated — either a close event arrived with no matching open alert, or the payload’s status value isn’t one the integration’s Open/Close/Update rules recognize. Also remember the integration’s filters may be intentionally dropping the event.
Need help? Contact support@serval.com for assistance with your AlertOps integration.