ITOC360 Python SDK

Python client for the ITOC360 Events API.

ITOC360 is an incident management and on-call platform. This SDK sends events to an ITOC360 source, which runs them through your escalation policies, on-call schedules and notification channels — SMS, voice calls, email and push.

No dependencies outside the standard library.

Installation

pip install itoc360

Requires Python 3.10 or later.

Quick start

import os

import itoc360

client = itoc360.Client(os.environ["ITOC360_TOKEN"])

client.send_alert(
    itoc360.Alert(
        fingerprint="db-primary-disk-full",
        summary="Disk usage on db-primary is at 95%",
        severity=itoc360.Severity.CRITICAL,
        status=itoc360.Status.FIRING,
    )
)

Authentication

Every request carries a source token. Create a source in the ITOC360 app, choose its provider type, and copy the token it generates. The token identifies both the organization the events belong to and the payload format the endpoint expects.

The SDK sends it as an RFC 6750 bearer token. Read it from the environment or a secret store — never commit it, and never put it in a URL.

Sending alerts

send_alert takes a provider-independent Alert and expands it into the Prometheus Alertmanager webhook payload:

alert = itoc360.Alert(
    fingerprint="db-primary-disk-full",
    summary="Disk usage on db-primary is at 95%",
    description="The data volume has less than 5% free space left.",
    severity=itoc360.Severity.CRITICAL,
    status=itoc360.Status.FIRING,
    labels={"instance": "db-01", "service": "payments"},
)

event = client.send_alert(alert)
print(event.id, event.type)  # -> "...", "ALERT"

Resolve it later by sending the same fingerprint with Status.RESOLVED:

client.send_alert(
    itoc360.Alert(
        fingerprint="db-primary-disk-full",
        summary="Disk usage on db-primary is back to normal",
        status=itoc360.Status.RESOLVED,
    )
)

Fingerprints

fingerprint is the deduplication key. ITOC360 groups every event carrying the same fingerprint into one alert, so an event whose fingerprint matches an open alert updates it instead of paging someone again.

Derive it from whatever makes the condition unique — the host, the check and the object it watches — and keep it identical between the firing and the resolved event. A value that changes per run raises a new alert every time.

Severity

severity becomes the alert's priority in ITOC360:

Severity	Priority
Severity.CRITICAL	CRITICAL
Severity.ERROR	HIGH
Severity.WARNING	MEDIUM
Severity.INFO	LOW

Defaults to Severity.WARNING.

Which sources send_alert works with

send_alert produces the Alertmanager payload, so the source must be configured for a provider that speaks it:

prometheus · mimir · cortex · loki · signoz · grafana

Other providers

ITOC360 supports over forty providers, each expecting its own vendor payload — Datadog, Zabbix, Dynatrace, CloudWatch, Splunk and the rest. send_raw sends any value that encodes to JSON and imposes no shape of its own:

client.send_raw(
    {
        "alert_id": "42",
        "alert_transition": "Triggered",
        "alert_title": "CPU high on web-03",
        "alert_type": "error",
    }
)

Match the payload to the provider your source is configured for; see the ITOC360 documentation for each format.

Configuration

client = itoc360.Client(
    token,
    base_url="https://itoc360.internal.example",
    timeout=10.0,
    user_agent="acme-pager/2.1",
)

Argument	Purpose
base_url	Point at a self-hosted deployment or a test server
timeout	Seconds to wait for each request; defaults to 30
user_agent	Identify your application in ITOC360's request logs
opener	A urllib.request.OpenerDirector for proxies or custom TLS

Error handling

A rejected request raises APIError, carrying the status and the server's own message. Neither the token nor any request header ever appears in it.

try:
    client.send_alert(alert)
except itoc360.APIError as error:
    if error.unauthorized:
        ...  # the token is missing or matches no source
    elif error.subscription_inactive:
        ...  # the subscription has lapsed; the event was dropped
    elif error.retryable:
        ...  # a server-side failure — worth sending again
except itoc360.TransportError:
    ...  # the request never reached ITOC360

An Alert missing its fingerprint or summary raises ValidationError before any request is made. Every exception derives from ITOC360Error.

Type checking

The package ships a py.typed marker, so mypy and pyright see the annotations without a stub package.

Development

python -m venv .venv && source .venv/bin/activate
pip install pytest mypy ruff

pytest
ruff check .
mypy

The package is importable straight from the checkout, so the tests need no install. They run against a local HTTP server and never contact ITOC360.

Links

• itoc360.com — product
• itoc360.app — sign in
• docs.itoc360.com — documentation
• itoc360-go — the Go SDK

License

Apache License 2.0. Copyright 2026 ITOC360 INC. See LICENSE.