Webhooks
A signed JSON POST for each backup event, to Slack, Teams, n8n, Zapier or a receiver of your own. The fields, the headers and the rules.
A webhook sends each backup event to an address of yours as a JSON POST. Use it if your alerts already go somewhere: a Slack channel, a Teams room, an n8n or Zapier flow, or a script on a server. Webhooks are part of Pro. The background agent sends them, with the window open or closed.
Set it up#
Open Settings ▸ Notifications ▸ Webhook:
| Field | What to enter |
|---|---|
| Webhook URL | an address that starts with https://. Plain http:// is accepted only for localhost or 127.0.0.1, to test a receiver on this PC. |
| Secret | optional. Every call is signed with it. It is stored encrypted on this PC and never shown again. |
| Send on | Run started, Run completed, Run failed (the default), Run completed with skipped files, Destination unreachable |
The webhook is on as soon as a URL is saved. Clear the URL to stop it.
Send a test event posts one test event and shows the answer: The endpoint answered 200. Anything other than a 2xx answer is E-NOTIFY-002, with the status.
The events#
event value | Sent when |
|---|---|
run.started | a backup starts |
run.completed | a backup completes |
run.failed | a backup fails, or is interrupted (the PC or GBM AI stopped during it) |
run.skipped | a backup completes with skipped files |
destination.unreachable | a job's drive is not connected shortly before a run, or a run failed because its destination could not be reached |
test | you pressed Send a test event |
A stopped run sends nothing.
The request#
One POST per event, with these headers:
Content-Type: application/json
User-Agent: GBM-AI-Webhook/1
X-GBMAI-Event: run.failed
X-GBMAI-Signature: sha256=<HMAC-SHA256 of the raw body, in hex>X-GBMAI-Signature is present only when a secret is set. To check it, compute the HMAC-SHA256 of the raw body with the same secret and compare.
The agent waits 20 seconds for an answer. It follows a redirect only if it is a 307 or 308 to an https:// address, at most three times. Any other redirect is refused and nothing is delivered.
The body#
| Field | Meaning |
|---|---|
event | one of the event values above |
product | GBM AI |
version | the agent's version, for example 10.0.56 |
host | the PC's name |
at | when it was sent, RFC 3339 in UTC |
jobId, jobName | the job |
runId | the run |
state | running, completed, completed_with_skips, failed or interrupted |
code, message | the error code and its message, when the run failed |
counters | new, updated, unchanged, deleted, skipped, errors |
bytes | read, written, and ratio (written against read) |
duration | how long the run took, for example 4m12s |
startedBy | schedule, user, ai, cli or shortcut |
Fields with no value are left out. A destination.unreachable warning before a run carries the job and a message only; a test event carries product, version, host, at and a message.
Slack and Teams#
Both accept a JSON POST through an incoming webhook, but each expects its own message shape. Put a small relay in between, such as n8n, Zapier, Power Automate or a few lines of your own. It reads the GBM AI body, checks the signature, and posts the text you want.