Integrations

Webhook events

Every event a webhook channel can get, what its body carries, how to check the signature, and how retries work.

A webhook channel gets an HTTPS POST from Enlist for each event it chose. Make one in Settings → Notifications (see Notifications). This page lists every event, what its body carries, and how to check that a body really came from Enlist.

Every delivery #

Headers #

HeaderValue
Content-Typeapplication/json; charset=utf-8
User-AgentEnlist-Webhooks/1
Enlist-EventThe event, such as onboarding.failed
Enlist-DeliveryOne id per delivery, the same on every try, so you can drop repeats
Enlist-Signaturet=<unix seconds>,v1=<hex>

Body #

{
  "id": "6f1c…",
  "type": "onboarding.failed",
  "createdAt": "2026-11-14T09:00:00+00:00",
  "data": { }
}

id names the event, so two channels that both get it see the same id. data depends on the event (below). Fields can be null, and new fields can be added at any time, so ignore the ones you don't know.

Check the signature #

v1 is HMAC-SHA256 over "{t}.{body}", keyed with the channel's signing secret (it starts with whsec_, and the whole secret is the key) as UTF-8, written as lowercase hex. Compute it over the raw body exactly as received, before any JSON parsing, compare in constant time, and refuse a t more than five minutes from your clock so an old body can't be replayed.

Python #

import hashlib, hmac, time

def from_enlist(secret: str, signature_header: str, raw_body: bytes) -> bool:
    parts = dict(p.split("=", 1) for p in signature_header.split(","))
    if abs(time.time() - int(parts["t"])) > 300:
        return False
    expected = hmac.new(secret.encode(), f"{parts['t']}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts["v1"])

Node.js #

import crypto from "node:crypto";

// rawBody is the request body as a Buffer, before any JSON parsing.
export function fromEnlist(secret, signatureHeader, rawBody) {
  const parts = Object.fromEntries(signatureHeader.split(",").map((p) => {
    const i = p.indexOf("=");
    return [p.slice(0, i), p.slice(i + 1)];
  }));
  const t = Number(parts.t);
  if (!Number.isInteger(t) || Math.abs(Date.now() / 1000 - t) > 300) return false;
  const expected = crypto.createHmac("sha256", secret).update(`${parts.t}.`).update(rawBody).digest();
  const given = Buffer.from(parts.v1 ?? "", "hex");
  return given.length === expected.length && crypto.timingSafeEqual(given, expected);
}

PowerShell 7 #

function Test-FromEnlist([string]$Secret, [string]$SignatureHeader, [byte[]]$RawBody) {
    $parts = @{}
    foreach ($p in $SignatureHeader.Split(',')) { $k, $v = $p.Split('=', 2); $parts[$k] = $v }
    $now = [DateTimeOffset]::UtcNow.ToUnixTimeSeconds()
    if ([Math]::Abs($now - [long]$parts['t']) -gt 300) { return $false }
    $hmac = [System.Security.Cryptography.HMACSHA256]::new([Text.Encoding]::UTF8.GetBytes($Secret))
    $signed = [byte[]]([Text.Encoding]::UTF8.GetBytes("$($parts['t']).") + $RawBody)
    $expected = $hmac.ComputeHash($signed)
    $given = [Convert]::FromHexString($parts['v1'])
    return [System.Security.Cryptography.CryptographicOperations]::FixedTimeEquals($expected, $given)
}
Keep the secret secret

Enlist shows a webhook channel's signing secret only once, when you add the channel (Copy secret, then I've saved it). Store it where your receiver reads its other secrets. If it leaks, add a new channel, move your receiver to its secret, then Remove the old channel.

Delivery and retries #

Answer with any 2xx within 5 seconds. Do the real work after you answer, for example by putting the event on your own queue.

  • A 408, 429 or 5xx, no answer in time, or no connection is tried again with growing waits (30 seconds, 1, 2, 4 minutes and so on, at most an hour apart), 12 tries in all over about five hours.
  • Any other answer (a 3xx or another 4xx, such as 400, 404 or 409) fails the delivery for good. Answer 503 when you only can't take it right now.
  • Enlist posts only to public addresses on port 443 and doesn't follow redirects.
  • The same event can arrive more than once. Use Enlist-Delivery (or the body's id) to drop repeats.

A channel's History button in the console shows its recent deliveries and the answers they got.

Onboarding events #

EventWhen
onboarding.blockedA device's onboarding stopped on a step that needs someone
onboarding.failedA device's onboarding failed
onboarding.rejectedA new device was not onboarded because its blueprint has no steps for its platform. Nothing ran on it
onboarding.succeededA device finished onboarding and is ready
onboarding.cancelledSomeone cancelled a device's onboarding
standard.failedA device's daily standard check found drift it couldn't fix

data:

{
  "sessionId": "…",
  "state": "failed",
  "error": "…",
  "device": { "id": "…", "hostname": "WL-LT-014", "serialNumber": "…", "model": "…" },
  "client": { "id": "…", "name": "Woodlands Law" },
  "site": { "id": "…", "name": "Main office" },
  "blueprint": "Woodlands laptops",
  "consoleUrl": "https://…"
}

onboarding.rejected has no session. Its data says why the device was sent back and what to fix, and consoleUrl opens the device:

{
  "state": "rejected",
  "reason": "no_plan_for_platform",
  "message": "Woodlands Macs has no steps for Windows devices.",
  "fix": "Add steps for Windows PCs to Woodlands Macs and publish it, or give the device another blueprint. Then start its onboarding from the device's page.",
  "device": { "id": "…", "hostname": "WL-LT-014", "serialNumber": "…", "platform": "windows" },
  "client": { "id": "…", "name": "Woodlands Law" },
  "site": { "id": "…", "name": "Main office" },
  "blueprint": "Woodlands Macs",
  "blueprintId": "…",
  "consoleUrl": "https://…/devices/…"
}

It is sent once, when the device enrolls. A channel limited to one client gets only that client's devices.

Patching events #

EventWhen
patching.os_patch_haltedAn OS patch rollout stopped because too many devices failed it
patching.app_patch_haltedAn app update rollout stopped because too many devices failed it

data: alert (os_patch_halted or app_patch_halted), patchId, title, ring, sent, failed, rolledBack, rollbackQueued, needBlueprint and consoleUrl.

EventWhen
patching.exception_endingA patch exception ends in a week (a day, for one shorter than two weeks)
patching.exception_endedA patch exception ended, so the patch installs there again

data: alert (exception_ending or exception_ended), patch (os or app), patchId, holdId, title, where (the client or device), deviceId, clientId, wholeApp, reason, owner, expiresAt and consoleUrl.

patching.monthly_report (the monthly patch report) goes to email channels only.

reports.client_monthly and reports.client_quarterly (branded client IT reports, Pro +) go only to email channels for one client, each with that client's own report.

Security events #

EventWhen
security.trusted_passkeys_changedThe passkeys devices trust to approve work changed
security.sign_in_changedSomeone's sign-in methods changed
security.account_recoveredSomeone recovered their account
security.approval_failuresPasskey approvals kept failing
security.mass_action_pausedEnlist paused someone doing many risky actions at once
security.mass_action_releasedSomeone released a paused mass action
security.agent_update_haltedAn agent update rollout stopped
security.sealing_key_changedThe key that seals device secrets changed
security.connector_enrolledA domain join connector was set up
security.connector_changedA domain join connector was changed or retired
security.uninstall_rule_changedA rule for removing software changed
security.certificate_reusedA device used a certificate that was replaced
security.protected_hostnameAn enrolled device reported the name of one of your protected machines
security.find_my_changedA Mac's Find My changed
security.admin_addedSomeone was made an owner or admin
security.role_changedSomeone's role changed
security.sign_in_failuresSign-ins kept failing
security.bulk_secret_viewsSomeone viewed many device secrets in a short time

data: alert (the event without security.), action (the activity log action behind it), actor ({ id, name }), ip, count, pausedAction, pausedUserId, targetUserId, role, auditSeq (its activity log entry) and consoleUrl. Two differ:

  • security.agent_update_halted: alert, action, agentUpdate ({ platform, architecture, version, ring }), judged, failed, auditSeq and consoleUrl.
  • security.find_my_changed: alert, action, device ({ id, hostname }), before, after, auditSeq and consoleUrl.

Approval events #

EventWhen
approval.requestedA blueprint publish or a step skip still needs another owner's or admin's passkey approval

data: what (blueprint or step_skip), id (the blueprint version or the skip), title (such as "Publish Front desk PCs, version 4"), clientId (null for blueprints for every client), requestedBy (who asked or approved last) and consoleUrl. Approve it in the console on the Today page, or on the blueprint or onboarding session. A person's phone gets it only when they are an owner or admin for the whole MSP. See The phone app.

Mail events #

EventWhen
mail.relay_failedYour own mail server (Pro +, Settings → Sending email) didn't take an email, so it went out from EnlistIt's address instead. Sent once per outage

data: error (your server's answer, one line), fellBack (whether EnlistIt's address sent it), at and consoleUrl (Settings → Sending email). It isn't sent again until a send through your server works. See Send email from your own domain.

{
  "error": "Your mail server smtp.office365.com:587 refused the user name or password. Check them, or use an app password if the account has MFA.",
  "fellBack": true,
  "at": "2026-11-17T14:30:00Z",
  "consoleUrl": "https://…/settings"
}

Test event #

A channel's Send test button sends type notification.test with data { "message": "This is a test from Enlist. Your channel works." }.

Last updated 2026-11-14. Something wrong or missing? Email [email protected].