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 in | Reads | Who may create it |
|---|---|---|
| a tenant | only that tenant | anyone allowed to set up 365 Backup and to manage API keys |
| a partner account | its own account and every customer tenant of the partner account | only 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:readand 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
| Address | https://conbool.com/api/v1/backup, or the address of your own installation (Copy URL) |
| Authentication | header Authorization: Bearer <key>; keys start with csk_live_ |
| Scope | backup:read |
| Limit | 60 requests per key and minute, shared by all requests of that key under /api/v1 |
| Block | after 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
| Endpoint | Returns |
|---|---|
GET /api/v1/backup/tenants | the 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}/sources | every item of the tenant with its state and last backup |
GET /api/v1/backup/tenants/{slug}/jobs | running 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
| Parameter | Meaning |
|---|---|
limit | entries per page, 1 to 200, default 50. Larger values count as 200. |
cursor | the 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": []
}
| Field | Meaning |
|---|---|
status | not_configured, breached, at_risk, pending or healthy; see the rule below |
counts | items 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_type | per kind of item (type): all items (total) and how many of them are backed up (protected) |
by_protection | all items per value of protection, including those not being backed up |
storage_bytes | storage used in bytes, null if it could not be read |
connections | per 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.sourcesis 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 incounts.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.
| Field | Meaning |
|---|---|
type | the kind of item: mailbox, archive, groupMailbox, drive, list, teams, planner, chat or directory |
name | display name, otherwise the address |
address | sign-in or object address, otherwise null |
url | web address at Microsoft, where known |
active | true if the item is being backed up |
state | healthy, 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. |
protection | whether it is backed up; values below |
paused_reason | the named reason when it is not backed up, with the same values as protection, otherwise null |
last_success_at, last_attempt_at | last successful backup and last attempt, successful or not |
rpo_hours | the backup target in hours that the state is measured against |
m365_tenant_id | ID of the Microsoft tenant |
Values of protection and paused_reason:
| Value | Meaning |
|---|---|
protected | backed up |
paused | not in the backup, no reason recorded |
paused_manually | switched off by hand |
erased | erased under Article 17 GDPR |
created_by_restore | created by a restore |
removed_at_microsoft | no longer exists at Microsoft |
not_licensed | above the seat count, not licensed |
excluded_by_rule | excluded by an exclusion rule |
room_or_equipment | room or equipment mailbox, not selected |
not_selected | not selected yet |
exempted | exempted by the customer, does not use a seat |
organization_paused | the whole organization is paused; existing backups stay until the deletion date |
other | a 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 withlimitandcursoras for tenants. The API returns no older ones, not even viacursor: paging only works within these 50, solimit=50returns nonext_cursor. The cursor is tied to the start time and ID of the last job on the page.source_idrefers toidin/sourcesand can benull.kind:initial(first backup),delta(incremental backup),restore,verify(verification). Exports are not in this list.status:running,succeeded,failedoraborted.itemsandbytes: what the run stored.error: set only forfailedandaborted, otherwisenull. An object withcode,messageanddetail.note: the remark of a successful or running job in the same form, for example skipped channels; otherwisenull. A job with anoteis 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.
code | Meaning |
|---|---|
source_empty | the source holds nothing to back up. The run stored nothing and still counts as successful. |
empty_snapshot_discarded | Microsoft returned an empty snapshot. It was not stored as a backup. |
nothing_read | the run neither read nor stored any items |
service_restarted | a service restart interrupted the run. What was stored until then is kept; the next cycle continues. |
token_unavailable | Microsoft issued no access token. The app is missing in the Microsoft organization, or its consent was revoked. |
malware_blocked | Microsoft blocked items it flagged as malware |
items_failed | some items could not be backed up |
channels_skipped | private or shared channels were skipped because they have their own permissions |
nothing_to_restore | nothing was backed up for this source at the chosen point in time |
already_present | during a restore, some items already existed in the original folder and were not created twice |
restored_as_draft | pages were restored as drafts. Check and publish them in SharePoint. |
microsoft_error | Microsoft Graph returned an error |
other | a 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": "…" } }.
| Status | error.code | Meaning |
|---|---|---|
| 400 | backup.invalid_parameter | limit or cursor is invalid. A cursor is only valid unchanged from next_cursor of the same list. parameter names the parameter. |
| 401 | among 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_mismatch | key 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 |
| 403 | siem.scope_missing | the key lacks backup:read |
| 404 | backup.tenant_not_found | tenant unknown, out of reach for this key, or without 365 Backup |
| 429 | siem.rate_limited | too many requests or too many failed authentications. The response carries Retry-After: 60. |
| 500 | backup.internal_error | unexpected 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.
| Field | Content |
|---|---|
| Action | backup.api.read |
| Actor | api: followed by the key prefix, as the key list shows it |
| Subject | sources or jobs |
route | sources or jobs again; the log picks its sentence from it |
key | ID of the key |
keyAccount | ID of the account that owns the key, so for a partner key the partner account |
foldedReads | only 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
| Event | In the portal | When |
|---|---|---|
backup.alarm_raised | Backup alarm | a backup alarm for the tenant is new or has changed |
backup.alarm_resolved | Backup running again | backups 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"
}
}
]
}
| Field | Meaning |
|---|---|
payload.tenant | the tenant as in /tenants. reference only in the delivery to the partner. |
alarm.severity | the 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.finding | the kind of finding, otherwise null. Always kunde:wieder-ok for backup.alarm_resolved. |
alarm.title, alarm.text | title and text of the alarm |
alarm.affected | up to 50 affected items. affected_total gives the full number. Empty for backup.alarm_resolved. |
alarm.detected_at | when the platform received the alarm |
portal_url | the tenant's 365 Backup overview in the portal |
event_time | when 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.
| Header | Content |
|---|---|
Content-Type | application/json |
User-Agent | Conbool-Webhook/1.0 (+https://conbool.com/docs/mailguard/siem-export) |
X-Conbool-Signature | sha256= followed by the HMAC-SHA256 over timestamp, dot and body |
X-Conbool-Signature-Previous | only during the transition after rotating the signing secret: the same signature with the old secret |
X-Conbool-Timestamp | time of signing in seconds since 1970 |
X-Conbool-Delivery-Id | ID of this delivery attempt, new on every attempt |
X-Conbool-Event-Count | number 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
- Take the body exactly as received, without reformatting it.
- Concatenate
X-Conbool-Timestamp, a dot and the body. - Compute HMAC-SHA256 over that with the signing secret, as hex. The secret is used as text, exactly as it was shown.
- Compare with the value after
sha256=inX-Conbool-Signature, in constant time. - 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
httpsaddresses 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.