Inbound Integrations, Alert Ingestion and Heartbeats with the AlertOps SDKs

Overview

Relevant for Developers wiring monitoring tools into AlertOps

An inbound integration is how alerts get into AlertOps. Each one has an ingest URL, an escalation policy (or response play) and recipient groups. Every SDK covers the whole integration editor through inbound: mapping, filters, delaying and grouping, override rules, dynamic recipient groups, access and the inbound log. It posts payloads through ingest and manages heartbeat monitors through heartbeats.

Key capabilities:

• One-call creation — inbound.create_api builds a Custom API integration with a unique source and returns the full record, including api_url.
• Safe cloning — inbound.clone_unique clones and re-sources in one step, so the clone gets its own URL.
• Keyless ingestion — ingest.post_to_integration reads the integration's api_url and posts to it. The URL itself is the credential.
• Heartbeats — heartbeats.create, heartbeats.ping and heartbeats.status cover a monitor end to end.

Reading the operation names

Relevant for Developers using any of the five AlertOps SDKs

This guide applies to every AlertOps SDK. It names each operation by its resource path and operation name, such as groups.members.add_users, lists positional arguments in order, and shows request bodies and options as JSON. Where a task needs real code, the example is given in all five languages. Each SDK spells the same call in its own style:

• Names follow each language's style: update_basic is updateBasic in TypeScript and Java, UpdateBasic in Go and UpdateBasicAsync in .NET. Go keeps initialisms upper case (create_api is CreateAPI, post_to_url is PostToURL).
• Paginated operations also have variants that collect every page or iterate lazily (…All / …Iter; in Python, .all() and .iter() on the operation).
• Helpers that look something up return null (None in Python, nil in Go) when nothing matches. **ensure helpers** return the record together with a flag that says whether it was created.
• Errors are the same classes in every SDK, such as NotFoundError and BadRequestError.
• Code examples come in the order Python, TypeScript, Go, Java, .NET. Each assumes a client named ao (and, in Go, a ctx and a function that returns error), created as in that SDK's Getting Started article.

For one language's details, see Calling the API from Python, TypeScript, Go, Java or .NET.

Before you start

Relevant for Developers setting up the client

You need an escalation policy id (or a response play id) and the names of the recipient groups. Group names, not ids, are what the create body takes.

Create an API integration

Relevant for Developers adding a new alert source

inbound.create_api(name, options) creates a Custom API integration (JSON over POST) and returns the full record read back from the API, including inbound_integration_id and api_url. With these options, api_url ends in /POSTAlert/<account token>/paymentsprod:

{"source": "paymentsprod", "escalation_policy_id": 12345, "recipient_groups": ["NOC"]}

Creating that integration and posting a first alert to it (see Send alerts in below):

Python

integration = ao.inbound.create_api("Payments Monitoring", source="paymentsprod",
                                    escalation_policy_id=12345, recipient_groups=["NOC"])
print(integration["api_url"])        # https://notify.alertops.com/POSTAlert/<account token>/paymentsprod
request_id = ao.ingest.post_to_integration(integration["inbound_integration_id"],
                                           {"subject": "Disk full on db-01", "description": "92% used on /var"})

TypeScript

const integration = await ao.inbound.createApi("Payments Monitoring", {
  source: "paymentsprod", escalation_policy_id: 12345, recipient_groups: ["NOC"],
});
console.log(integration.api_url);   // https://notify.alertops.com/POSTAlert/<account token>/paymentsprod
const requestId = await ao.ingest.postToIntegration(integration.inbound_integration_id,
  { subject: "Disk full on db-01", description: "92% used on /var" });

Go

integration, err := ao.Inbound.CreateAPI(ctx, "Payments Monitoring", alertops.M{
	"source": "paymentsprod", "escalation_policy_id": 12345, "recipient_groups": []any{"NOC"},
})
if err != nil {
	return err
}
fmt.Println(alertops.Get(integration, "api_url")) // https://notify.alertops.com/POSTAlert/<account token>/paymentsprod
requestID, err := ao.Ingest.PostToIntegration(ctx, alertops.Get(integration, "inbound_integration_id"),
	alertops.M{"subject": "Disk full on db-01", "description": "92% used on /var"})

Java

JsonNode integration = ao.inbound().createApi("Payments Monitoring", Map.of(
    "source", "paymentsprod", "escalation_policy_id", 12345, "recipient_groups", List.of("NOC")));
System.out.println(integration.get("api_url"));   // https://notify.alertops.com/POSTAlert/<account token>/paymentsprod
JsonNode requestId = ao.ingest().postToIntegration(integration.get("inbound_integration_id"),
    Map.of("subject", "Disk full on db-01", "description", "92% used on /var"));

.NET

var integration = await ao.Inbound.CreateApiAsync("Payments Monitoring", new Kwargs
{
    ["source"] = "paymentsprod", ["escalation_policy_id"] = 12345, ["recipient_groups"] = new[] { "NOC" },
});
Console.WriteLine(integration?["api_url"]);   // https://notify.alertops.com/POSTAlert/<account token>/paymentsprod
var requestId = await ao.Ingest.PostToIntegrationAsync(integration!["inbound_integration_id"]!,
    new JsonObject { ["subject"] = "Disk full on db-01", ["description"] = "92% used on /var" });

source is the last segment of the ingest URL and must be unique; recipient_groups are group names. If you leave out source, the SDK generates a random one (sdk plus 12 hex characters). Pass response_play_id instead of escalation_policy_id to route to a response play.

Clone without sharing a URL

inbound.clone copies the source, so the clone and the original share an ingest URL. Use inbound.clone_unique(integration_id, name, source) instead, for example with the name Payments Monitoring (staging) and the source paymentsstaging. It clones, then writes the new source into the clone's mapping, so the clone's api_url differs from the original's.

Template integrations can have the same problem: a ConnectWise Manage template integration gets the fixed source CWManageTicket. Re-source it straight after creating it with inbound.mapping.update(integration_id, {source: …, source_value: …}).

Inbound integration operations

inbound.catalog holds the editor's pickers (types, api_templates, filter_types, api_filter_types, v3_filter_types and more). The legacy ConnectWise and time-of-day override endpoints are listed in each SDK's method reference.

Change the mapping

Relevant for Developers adjusting how payload fields map to alert fields

The API mapping lives in api_settings.url_mapping on the integration record. Both write endpoints replace the whole mapping, so a partial body blanks every field you leave out. inbound.mapping.update(integration_id, changes) reads the current mapping, overlays your changes and saves the whole thing. For example, these changes map the subject and short text:

{"subject": "<subject>", "short_text": "<description>"}

Filter which events open alerts

Relevant for Developers dropping noise before it becomes an alert

There are two filter APIs. The classic editor uses the v2 filter sets. The new UI's Which events to filter editor uses v3 rule filters.

Classic filters (v2)

A v2 filter set has a match-all list (add_all_filter) and a match-any list (add_any_filter). inbound.filters.add(integration_id, field_name, type, value, {match, negate}) adds one condition to either list and returns the whole set:

To edit a filter, pass the id as the path value and in the body: inbound.filters.update(iid, filter_id, {body: …}) with

{"filter_id": 4411, "condition": {"field_name": "Body", "type": "Contains", "value": "payments"}, "not": false}

New-UI rule filters (v3)

Rule filters are IF / ELSE IF rules: only events that match a rule are processed. fieldName is a mapped token such as <subject>, and type is a value from inbound.catalog.v3_filter_types() (for example Contains or Matches Regex).

{"category": 1, "isOrClause": false,
 "conditions": [{"fieldName": "<subject>", "type": "Contains", "value": "PRD", "conditionGroup": 1, "not": false, "sortOrder": 1}]}

Pass or_clause: true to rule_filters.add to make the rule an OR clause. There is no reorder endpoint for rule filters (404).

Delay or group notifications

Relevant for On-call admins reducing notification bursts

delaying_grouping controls whether alerts arriving close together are grouped into one alert, or whether notifications are delayed. Both helpers write the rule and return the read-back:

• inbound.delaying_grouping.group_within(iid, 7) groups alerts that arrive within 7 minutes.
• inbound.delaying_grouping.delay_every(iid, 5) sends one notification every 5 minutes.

Route alerts with override rules and dynamic groups

Relevant for On-call admins sending some alerts to a different policy or team

Override rules switch the escalation policy (or response play) when data and time conditions match. Dynamic groups switch the recipient group.

Escalation policy override rules

inbound.override_rules.create(integration_id, fields) with these fields switches to policy 23456 on weekdays from 09:00 to 17:00 when the body contains database:

{
  "escalation_policy_id": 23456, "sort_order": 1,
  "time_condition": {
    "week": {"sun": false, "mon": true, "tue": true, "wed": true, "thu": true, "fri": true, "sat": false},
    "start_time": {"hour": 9, "minute": 0}, "end_time": {"hour": 17, "minute": 0}
  },
  "data_conditions": [{"condition_group": 1, "field_name": "Body", "type": "Contains", "value": "database",
                       "not": false, "sort_order": 1}]
}

create returns the full rule list (escalation_policy_id reads back as a string). Each rule needs a unique sort_order; duplicates are rejected. override_rules.reorder takes [{override_rule_id, sort_order}] for every rule. An update re-creates the data conditions with new ids.

Dynamic recipient groups (v2 and v3)

The v2 endpoint replaces the whole rule list. It takes the group name and reads back the group id (as a string) plus group_name. inbound.dynamic_recipients.set(iid, rules) takes a list like this:

[{"condition": {"field_name": "Body", "type": "Contains", "value": "payments"}, "recipient_group": "Payments"}]

The v3 endpoints see the same rules in camelCase (ruleId, groupId). inbound.dynamic_groups.add(iid, group_id, conditions) appends one rule with the next sortOrder, for example with the conditions [{fieldName: "Body", type: "Contains", value: "db"}]. Move it with inbound.dynamic_groups.reorder(iid, [{ruleId: …, sortOrder: 1}]).

Control access

Relevant for App Admins restricting who can edit an integration

Turn on custom access, then add users or groups. Use permission_id (3 View, 2 Edit). A permission: "View" string is ignored and stored as Edit.

Only users whose role carries the integrations entitlement and who don't have access yet are valid for add_admins (see admins_available). Others fail with "User: <id> is invalid".

Send alerts in

Relevant for Developers posting alerts from code or a monitoring bridge

ingest.post_to_integration(integration_id, payload) reads the integration's api_url and posts the payload there. The notify host takes no API key, and it answers 200 with the request id as a JSON string. If you already have the URL, ingest.post_to_url(api_url, payload) skips the read. A payload:

{"subject": "Disk full on db-01", "description": "92% used on /var"}

A payload that matches no open or close rule is still accepted with 200, so the response alone doesn't tell you whether an alert opened.

Figure 1. An alert posted through an SDK-created integration. The Summary panel shows Source SDKE2EMonitoring, the integration's unique source segment, plus the escalation policy and the three users notified.

Test an integration

inbound.test(integration_id) asks AlertOps to post its own test payload and returns the request id. It opens a real alert, so close it afterwards.

POST /{id}/testurl must have no body. Sending {} fails with "Method Type cannot be empty". inbound.test sends none for you.

Read the inbound log

Relevant for Developers confirming what happened to a payload

The log shows each inbound message with its mapping_status (Mapped Opened, Mapped Appended …) and the alert_id it produced. Rows appear within about 10 seconds.

• inbound.log.recent(integration_id, {days: 1}) returns the recent rows for one integration, each with message_id, mapping_status and alert_id.
• inbound.log.get(message_id) returns one message's detail: body, recipients and dates.

For a custom window, call the paginated variant of inbound.log.list with {datefrom, dateto} and filter on inbound_integration_id yourself.

Heartbeats

Relevant for Developers monitoring jobs that must check in on a schedule

A heartbeat is a v2 inbound integration of type Heartbeat. It alerts when no ping arrives within its interval. Creating, reading, updating and deleting go through the v2 inbound endpoints. Groups, status, uptime and analytics are v3 under /integrations/heartbeats.

The heartbeat's api_url is https://notify.alertops.com/Heartbeat/<per-heartbeat token>: it has no source segment, because each heartbeat has its own token. heartbeats.create requires an escalation policy id or response_play_id and raises ValueError otherwise.

A ping turns status to Up within seconds. Ranged analytics (with fromDate/toDate) was seen reporting 0% uptime for a day that had a successful ping, so treat per-day figures with care.

Best Practices

Relevant for Anyone running integrations in production

Routing

• Always pass an explicit, descriptive source to create_api, and never reuse one across integrations.
• Use clone_unique, never clone, unless you mean to share an ingest URL.
• Re-source template integrations (ConnectWise and others with a fixed source) right after creating them.

Writes

• Change mappings with mapping.update, never with a partial mapping.replace.
• Send only real changes to access.update_admins. A no-op entry removes the user.
• Give each override rule a distinct sort_order.

Testing

• Close alerts opened by inbound.test or test payloads, and confirm outcomes in the inbound log, not from the 200.

Configuration Examples

Relevant for Starting templates for common setups

Example 1 — Minimal: one integration and one test alert

Example 2 — Typical: filtered, grouped, with an after-hours override

{"escalation_policy_id": 23456, "sort_order": 1, "data_conditions": [],
 "time_condition": {
   "week": {"sun": true, "mon": true, "tue": true, "wed": true, "thu": true, "fri": true, "sat": true},
   "start_time": {"hour": 18, "minute": 0}, "end_time": {"hour": 23, "minute": 59}}}

Troubleshooting

Relevant for Anyone debugging alert ingestion

Alerts show up on the wrong integration

• Two integrations share a source, so they share an ingest URL. Compare api_url values and re-source one with inbound.mapping.update(iid, {source, source_name, source_value}).
• The integration is a clone made with clone. Re-source it, or recreate it with clone_unique.

A payload returned 200 but no new alert appeared

• An alert from the same integration was still open, so the payload was Mapped Appended to it. Check inbound.log.recent(iid) and close the open alert.
• The payload didn't match the filters or open-alert rules. Check the row's mapping_status and your rule_filters or filters.

The inbound log returns every integration's rows

• The integration query filter is ignored by the API. Use log.recent(iid) or filter on inbound_integration_id.
• A 400 from log.list means datefrom or dateto is missing. Both are required, as YYYY-MM-DDTHH:mm in the account time zone.

"Method Type cannot be empty" from testurl

• A body was sent with POST /{id}/testurl. Call inbound.test(iid), which sends none.

"User: <id> is invalid" when adding access

• The user's role lacks the integrations entitlement, or the user already has access. Pick from inbound.access.admins_available(iid, {includeGroups: true}).

402 from update_alert_tags

• Alert correlation tags need the Correlation package feature. PaymentRequiredError is expected without it.

Related Articles

• Working with Alerts in the AlertOps SDKs
• Escalation Policies and Response Plays with the AlertOps SDKs
• Workflows, Outbound Integrations and Maintenance Windows with the AlertOps SDKs
• Getting Started with the AlertOps Python SDK
• Getting Started with the AlertOps TypeScript SDK

Need help?

Email support@alertops.com or contact your AlertOps representative.