API and webhooks: Conbool 365 Backup in your RMM

The read-only API under /api/v1/backup for tenants, status, protected items and jobs, plus signed webhooks for backup alarms and their recovery.

The API lets an RMM system or your own tools read the state of Conbool 365 Backup: which tenants are backed up, how every mailbox, OneDrive and site is doing, and which jobs are running. Webhooks report backup alarms and their recovery to your own URL as they happen.

The API is read-only. Backing up, restoring and exports stay in the portal.

Who can use it

Key created inReadsWho may create it
a tenantonly that tenantanyone allowed to set up 365 Backup and to manage API keys
a partner accountits own account and every customer tenant of the partner accountonly the owner of the partner account, because the key reaches every customer

In both cases only tenants that have 365 Backup count. Personal accounts are never included.

A partner key sees, in the reference field of every customer tenant, the customer number the partner assigned. For the partner's own account and for every key created in a tenant, reference is always null.

A tenant the key may not read does not exist as far as the API is concerned. The answer is 404, not 403.

Creating a key and a target

Both live under Administration, Settings, tile SIEM and APIs, tab Connections, then 365 Backup. If the tenant has neither MailGuard nor SecureFiles, the tile is called API and the tab Keys.

  • Key: card 365 Backup API, button Create key. A name is enough; validity and an IP restriction are optional. The key is shown only once. It carries only the scope backup:read and opens no other API. Copy URL in the card menu gives you the API address. Existing keys can be rotated (Rotate) and revoked (Revoke).
  • Webhook target: card Webhooks for 365 Backup, button Add target. Enter the recipient URL and pick the events Backup alarm and Backup running again; both are preselected. The signing secret is shown only once.

Adding or changing a 365 Backup target, and changing or rotating a key, is limited to people who may also create the key. Targets additionally need the right to manage connections. In a partner account that is the owner alone, because a target there receives the alarms of every customer.

Address and authentication

Addresshttps://conbool.com/api/v1/backup, or the address of your own installation (Copy URL)
Authenticationheader Authorization: Bearer <key>; keys start with csk_live_
Scopebackup:read
Limit60 requests per key and minute, shared by all requests of that key under /api/v1
Blockafter 30 failed authentications within one minute from the same address, the API answers that address with 429

Every response is JSON and carries Cache-Control: no-store. Calls from a browser on another site are not supported: responses carry no cross-origin (CORS) permission.

curl -s -H "Authorization: Bearer csk_live_..." \
  "https://conbool.com/api/v1/backup/tenants?limit=100"

curl -s -H "Authorization: Bearer csk_live_..." \
  "https://conbool.com/api/v1/backup/tenants/example-ltd"

Endpoints

EndpointReturns
GET /api/v1/backup/tenantsthe tenants the key may read, page by page
GET /api/v1/backup/tenants/{slug}status of one tenant: traffic light, counts, storage, Microsoft 365 connections, no names
GET /api/v1/backup/tenants/{slug}/sourcesevery item of the tenant with its state and last backup
GET /api/v1/backup/tenants/{slug}/jobsrunning and recent jobs

{slug} is the tenant's short name from /tenants, the same one used in the portal address. An item is a single protected object: a mailbox, a OneDrive, a site, a team.

Tenants

GET /api/v1/backup/tenants

ParameterMeaning
limitentries per page, 1 to 200, default 50. Larger values count as 200.
cursorthe next_cursor value from the previous response, unchanged
{
  "tenants": [
    { "id": "…", "slug": "example-ltd", "name": "Example Ltd", "reference": "K-1042" }
  ],
  "next_cursor": null
}

The list is sorted by slug. next_cursor is null on the last page. The cursor is tied to the last slug of the page: if a tenant is added or removed between two pages, nothing shifts. A partner key sees at most 2000 customers.

Tenant status

GET /api/v1/backup/tenants/{slug}

{
  "tenant": { "id": "…", "slug": "example-ltd", "name": "Example Ltd", "reference": "K-1042" },
  "status": "at_risk",
  "counts": {
    "sources": 116,
    "healthy": 113,
    "at_risk": 2,
    "breached": 0,
    "first_backup_pending": 1,
    "paused": 0
  },
  "by_source_type": [
    { "type": "mailbox", "total": 64, "protected": 60 },
    { "type": "drive", "total": 58, "protected": 56 }
  ],
  "by_protection": [
    { "protection": "protected", "count": 116 },
    { "protection": "not_licensed", "count": 6 }
  ],
  "storage_bytes": 412316860416,
  "connections": [
    {
      "organization": "Example Ltd",
      "domain": "example.com",
      "last_success_at": "2026-11-17T02:47:12+00:00",
      "connection_lost_at": null,
      "missing_permissions": []
    }
  ],
  "incomplete": []
}
FieldMeaning
statusnot_configured, breached, at_risk, pending or healthy; see the rule below
countsitems that are meant to be backed up, per state. sources is their sum. The list under /sources also includes items that are not backed up (protection other than protected), so it is usually longer. paused counts those not being backed up right now, usually because the connection to Microsoft is missing.
by_source_typeper kind of item (type): all items (total) and how many of them are backed up (protected)
by_protectionall items per value of protection, including those not being backed up
storage_bytesstorage used in bytes, null if it could not be read
connectionsper connected Microsoft tenant: name, domain, last success, since when Microsoft no longer knows the connection, permissions the backup app is missing

missing_permissions is null as long as the permissions have never been checked, and an empty list once they were checked and nothing is missing.

How status is derived:

  • not_configured: no item is being backed up; counts.sources is 0.
  • breached: at least one item has no valid backup.
  • at_risk: at least one item is at risk or not being backed up right now (counts.paused), none is without a valid backup.
  • pending: no item is at risk or without a valid backup, but every item is still waiting for its first backup. This is what a newly set-up tenant looks like.
  • healthy: otherwise. Once at least one item is backed up, items still waiting for their first backup do not change the value. Their number is in counts.first_backup_pending.

status only rates the items. Whether the Microsoft connection works is shown by connection_lost_at and missing_permissions.

Items

GET /api/v1/backup/tenants/{slug}/sources

{
  "tenant": { "id": "…", "slug": "example-ltd", "name": "Example Ltd", "reference": "K-1042" },
  "sources": [
    {
      "id": "…",
      "type": "mailbox",
      "name": "Anna Example",
      "address": "anna@example.com",
      "url": null,
      "active": true,
      "state": "healthy",
      "protection": "protected",
      "paused_reason": null,
      "last_success_at": "2026-11-17T02:47:12+00:00",
      "last_attempt_at": "2026-11-17T02:47:12+00:00",
      "rpo_hours": 24,
      "m365_tenant_id": "…"
    }
  ],
  "next_cursor": null,
  "incomplete": []
}

The list is paged, with limit and cursor as for tenants. It is sorted by id; the cursor is tied to the last id of the page.

FieldMeaning
typethe kind of item: mailbox, archive, groupMailbox, drive, list, teams, planner, chat or directory
namedisplay name, otherwise the address
addresssign-in or object address, otherwise null
urlweb address at Microsoft, where known
activetrue if the item is being backed up
statehealthy, at_risk, breached, first_backup_pending or paused (not being backed up right now, for example because the connection to Microsoft is missing). Meaningful only when active is true.
protectionwhether it is backed up; values below
paused_reasonthe named reason when it is not backed up, with the same values as protection, otherwise null
last_success_at, last_attempt_atlast successful backup and last attempt, successful or not
rpo_hoursthe backup target in hours that the state is measured against
m365_tenant_idID of the Microsoft tenant

Values of protection and paused_reason:

ValueMeaning
protectedbacked up
pausednot in the backup, no reason recorded
paused_manuallyswitched off by hand
erasederased under Article 17 GDPR
created_by_restorecreated by a restore
removed_at_microsoftno longer exists at Microsoft
not_licensedabove the seat count, not licensed
excluded_by_ruleexcluded by an exclusion rule
room_or_equipmentroom or equipment mailbox, not selected
not_selectednot selected yet
exemptedexempted by the customer, does not use a seat
organization_pausedthe whole organization is paused; existing backups stay until the deletion date
othera reason the API does not name yet

Let your tool accept unknown values for type, state and protection.

Jobs

GET /api/v1/backup/tenants/{slug}/jobs

{
  "tenant": { "id": "…", "slug": "example-ltd", "name": "Example Ltd", "reference": "K-1042" },
  "running": [],
  "jobs": [
    {
      "id": "…",
      "source_id": "…",
      "kind": "delta",
      "status": "succeeded",
      "started_at": "2026-11-17T02:41:05+00:00",
      "finished_at": "2026-11-17T02:47:12+00:00",
      "items": 214,
      "bytes": 18874368,
      "error": null,
      "note": null
    }
  ],
  "next_cursor": null,
  "incomplete": []
}
  • running: what is running right now, up to 200 jobs, always complete and without paging.
  • jobs: the tenant's 50 most recent jobs, newest first, paged with limit and cursor as for tenants. The API returns no older ones, not even via cursor: paging only works within these 50, so limit=50 returns no next_cursor. The cursor is tied to the start time and ID of the last job on the page.
  • source_id refers to id in /sources and can be null.
  • kind: initial (first backup), delta (incremental backup), restore, verify (verification). Exports are not in this list.
  • status: running, succeeded, failed or aborted.
  • items and bytes: what the run stored.
  • error: set only for failed and aborted, otherwise null. An object with code, message and detail.
  • note: the remark of a successful or running job in the same form, for example skipped channels; otherwise null. A job with a note is not an error.
"error": {
  "code": "token_unavailable",
  "message": "Microsoft issued no access token. The app is missing in the Microsoft organization or its consent was revoked.",
  "detail": "kein Token: invalid_client …"
}

message is a fixed English sentence per code. detail is the run's own note, verbatim and usually in German. Evaluate code, not the texts. error and note use the same codes.

codeMeaning
source_emptythe source holds nothing to back up. The run stored nothing and still counts as successful.
empty_snapshot_discardedMicrosoft returned an empty snapshot. It was not stored as a backup.
nothing_readthe run neither read nor stored any items
service_restarteda service restart interrupted the run. What was stored until then is kept; the next cycle continues.
token_unavailableMicrosoft issued no access token. The app is missing in the Microsoft organization, or its consent was revoked.
malware_blockedMicrosoft blocked items it flagged as malware
items_failedsome items could not be backed up
channels_skippedprivate or shared channels were skipped because they have their own permissions
nothing_to_restorenothing was backed up for this source at the chosen point in time
already_presentduring a restore, some items already existed in the original folder and were not created twice
restored_as_draftpages were restored as drafts. Check and publish them in SharePoint.
microsoft_errorMicrosoft Graph returned an error
othera note the API does not classify yet. Read detail.

Let your tool accept unknown values for code; the list can grow.

Incomplete responses

Every response except /tenants carries incomplete. It names the parts that could not be read, for example units, runs, running, connections or storage-usage. units-truncated means the list of items was cut short.

If incomplete is not empty, an empty field does not mean "nothing there". If units is missing, for example, status reads not_configured. Check incomplete before you act on status.

Errors

Every error response has the shape { "error": { "code": "…" } }.

Statuserror.codeMeaning
400backup.invalid_parameterlimit or cursor is invalid. A cursor is only valid unchanged from next_cursor of the same list. parameter names the parameter.
401among others siem.invalid_key, siem.token_invalid, siem.key_revoked, siem.key_expired, siem.key_pending_approval, siem.ip_not_allowed, siem.mtls_unavailable, siem.client_certificate_mismatchkey missing, unknown, invalid, revoked, expired or not yet approved, the address is not allowed, or the required client certificate is missing or does not match
403siem.scope_missingthe key lacks backup:read
404backup.tenant_not_foundtenant unknown, out of reach for this key, or without 365 Backup
429siem.rate_limitedtoo many requests or too many failed authentications. The response carries Retry-After: 60.
500backup.internal_errorunexpected error
{ "error": { "code": "backup.invalid_parameter", "parameter": "limit" } }

Requests in the audit log

/sources and /jobs hand out names, addresses and error texts. Every such request is recorded in the audit log of the tenant that was read, under 365 Backup, Audit log, also when a partner key reads it. Requests to /tenants and /tenants/{slug} are not recorded there.

A tool that polls every five minutes should not flood the log. So there is at most one entry per key, tenant and endpoint per hour. Further requests within that hour get no entry of their own. The next entry states in foldedReads how many there were.

FieldContent
Actionbackup.api.read
Actorapi: followed by the key prefix, as the key list shows it
Subjectsources or jobs
routesources or jobs again; the log picks its sentence from it
keyID of the key
keyAccountID of the account that owns the key, so for a partner key the partner account
foldedReadsonly if greater than 0: requests since the last entry that got no entry of their own

A failed request hands out nothing and is not recorded. After a platform restart, or when several platform instances answer, there may be one entry more, never one fewer.

Webhooks

The events

EventIn the portalWhen
backup.alarm_raisedBackup alarma backup alarm for the tenant is new or has changed
backup.alarm_resolvedBackup running againbackups are running again after an alarm

An event comes from the notification "A backup failed or is overdue" in Notifications and reports. The daily summary, restores, exports and notices meant only for Conbool trigger none.

  • The event goes out right away, even if the tenant receives its notifications bundled once a day.
  • If the tenant has switched this notification off, no event is created either.

Who receives them

  • A target in a tenant receives that tenant's alarms.
  • A target in a partner account receives the alarms of every customer tenant and of its own account.
  • If both the tenant and the partner have a target, both receive the event, each with its own event_id.
  • Only targets that explicitly selected the 365 Backup events count. A target set to "all events" on another card does not receive them.

Delivery format

A delivery is a POST with up to 100 events in events, oldest first. The payload comes from the alarm; it never contains the content of mails or files.

{
  "events": [
    {
      "event_id": "…",
      "event_type": "backup.alarm_raised",
      "event_version": "1.0",
      "event_time": "2026-11-17T08:00:03.412+00:00",
      "ingest_time": "2026-11-17T08:00:03.418+00:00",
      "source_product": "backup",
      "payload": {
        "tenant": {
          "id": "…",
          "slug": "example-ltd",
          "name": "Example Ltd",
          "reference": "K-1042"
        },
        "alarm": {
          "severity": "breached",
          "finding": null,
          "title": "No valid backup",
          "text": "No backup for 30 hours.",
          "affected": ["anna@example.com", "Sales (SharePoint)"],
          "affected_total": 2,
          "detected_at": "2026-11-17T08:00:03.120Z"
        },
        "portal_url": "https://conbool.com/home/example-ltd/backup"
      }
    }
  ]
}
FieldMeaning
payload.tenantthe tenant as in /tenants. reference only in the delivery to the partner.
alarm.severitythe level: breached (no valid backup), errorObjects (objects fail repeatedly), probe (a restore probe failed, and any other alarm without a level of its own, such as a suspended automatic intake of a group), chain (log chain broken). For backup.alarm_resolved go by event_type, not by the level.
alarm.findingthe kind of finding, otherwise null. Always kunde:wieder-ok for backup.alarm_resolved.
alarm.title, alarm.texttitle and text of the alarm
alarm.affectedup to 50 affected items. affected_total gives the full number. Empty for backup.alarm_resolved.
alarm.detected_atwhen the platform received the alarm
portal_urlthe tenant's 365 Backup overview in the portal
event_timewhen the event was written

If the target's account uses the privacy mode Pseudonymised or Remove (tab Privacy & format, which exists only with MailGuard or SecureFiles), title, text and affected carry hashes or [REDACTED] instead of plain text. If custom fields are set up, payload.custom is added.

HeaderContent
Content-Typeapplication/json
User-AgentConbool-Webhook/1.0 (+https://conbool.com/docs/mailguard/siem-export)
X-Conbool-Signaturesha256= followed by the HMAC-SHA256 over timestamp, dot and body
X-Conbool-Signature-Previousonly during the transition after rotating the signing secret: the same signature with the old secret
X-Conbool-Timestamptime of signing in seconds since 1970
X-Conbool-Delivery-IdID of this delivery attempt, new on every attempt
X-Conbool-Event-Countnumber of events in events

Event ID and duplicates

Detect duplicates by event_id, not by X-Conbool-Delivery-Id.

  • A repeated delivery attempt carries the same events with the same event_id.
  • If the backup service reports the same incident again, with the same title, text, finding and affected items on the same day (UTC), no new event is created. The one event keeps its event_id.
  • If title, text, finding or the affected items change, that is a new event with a new event_id.
  • If an incident lasts past midnight (UTC) and is reported again on the new day, that is a new event.
  • If backups fail again after a recovery, that is a new event with a new event_id, even on the same day and with the same text. This also applies to a target that selected only Backup alarm.
  • Two recoveries on one day are two events.

A recovery does not point to the event of its alarm. Match the two by payload.tenant.id.

Verifying the signature

  1. Take the body exactly as received, without reformatting it.
  2. Concatenate X-Conbool-Timestamp, a dot and the body.
  3. Compute HMAC-SHA256 over that with the signing secret, as hex. The secret is used as text, exactly as it was shown.
  4. Compare with the value after sha256= in X-Conbool-Signature, in constant time.
  5. Reject deliveries with an old timestamp. Every attempt is signed afresh, so a window of a few minutes is enough.
import hashlib, hmac

def signature_ok(secret: str, timestamp: str, body: bytes, header: str) -> bool:
    expected = hmac.new(
        secret.encode(), timestamp.encode() + b"." + body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(header, "sha256=" + expected)

Rotate signing secret offers three options: 7-day transition, 1-day transition or replace immediately. During the transition, X-Conbool-Signature is signed with the new secret and X-Conbool-Signature-Previous with the old one. A receiver that still knows only the old secret checks that header.

Delivery and retries

  • Deliveries run every minute, only to https addresses and never to internal addresses. Redirects are not followed.
  • A delivery counts as successful on a 2xx status within ten seconds. Anything else is a failure.
  • After a failure the next attempt follows after 1, 5, 30 and then every 120 minutes. After ten failures in a row the target is paused until you choose Enable in its menu. Retry now in the target's menu skips the wait: the next attempt follows on the next run.
  • Whatever piles up in the meantime arrives with the next successful delivery, also after re-enabling. Events older than 30 days are no longer delivered, nor any the account no longer keeps (configurable between 7 and 365 days).
  • A new target first receives the events of the last 30 days that already exist for the account. Those are the ones from the time when the account already had a 365 Backup target.

Test in the target's menu sends {"ping": true, "at": "…"} with X-Conbool-Event-Count: 0, X-Conbool-Timestamp and X-Conbool-Signature from the current secret. Unlike a delivery it carries no X-Conbool-Signature-Previous, no X-Conbool-Delivery-Id and no User-Agent of its own. Answer it with 2xx.

Further reading

Which notifications exist and who receives them by mail is described in Notifications and reports. The Microsoft 365 connection and its permissions are covered in Setup. Back to the 365 Backup overview.