NetLock RMMNetLock RMM Docs
V — Appendix

Webhook signatures

How NetLock RMM signs webhook requests with X-NetLock-Signature, how a receiver verifies them in C#, Python and Node.js, and how signed webhooks are managed in the web console.

Webhook signatures

A receiver of a webhook has to answer two questions: did this request really come from NetLock RMM, and was its body changed on the way? A signature answers both. NetLock RMM computes it with a secret that only the instance and the receiver know, and sends it in the header X-NetLock-Signature.

The signature covers the timestamp and the body. It does not cover the URL, the query string, the method or any other header, so do not base a decision on those alone.

X.10.1 What is signed

Three kinds of webhook can carry the signature. All of them use the same format, so one verification routine covers them.

Signed webhooksWebhook notification channelTicket webhooks
Configured onSettings → Integrations → Signed webhooks, or /v1/webhooks of the Public APISettings → Notifications, Webhook tab (A.8.6)Tickets → Departments, Manage Webhooks (Chapter 10.16)
SignedAlwaysWith the switch Sign requests, off by defaultWith the switch Sign requests, off by default
MethodPOSTThe configured methodThe configured method
BodyThe JSON envelope type, id, createdAt, dataThe configured template after the placeholders were replaced; without a template a default JSON document with the event valuesThe configured template after the placeholders were replaced; without a template a default JSON document with the event values
Further headersX-NetLock-Event, X-NetLock-Webhook-Id, X-NetLock-DeliveryThe configured headersThe configured headers
RetriesYes, with a growing delayNoNo

With the switch off, requests of the notification channel and of ticket webhooks are sent unchanged.

Slack, Microsoft Teams, Discord and ntfy ignore signatures. The switch only helps with a receiver that checks them, such as your own endpoint or an automation platform.

X.10.2 The format

X-NetLock-Signature: t=1700000000,v1=cf7d053522b08300fae293c3bcbf4e183d4a9538620c18dc9a46d063337936fa
  • t is the time of the send in Unix seconds.
  • v1 is the lowercase hex HMAC-SHA256 of the exact string t + "." + body, keyed with the secret as UTF-8 text.
  • body is exactly what the request carries, as UTF-8. A request that carries no body, which is every GET and a test from a dialog with an empty template, is signed over the empty string. A real event with an empty template carries the default JSON document, and that is what is signed.

If the receiver has to tell requests without a body apart, use a method with a body.

Use this vector to test your code: the secret whsec_test, t = 1700000000 and the body {"type":"webhook.test"} give the v1 shown above.

X.10.3 How to verify a request

  1. Read the raw bytes of the body before any parser touches them. Parsing and serializing JSON again changes the bytes, and the signature no longer matches.
  2. Split the header into t and v1.
  3. Reject the request if t is more than a few minutes away from your own clock. Five minutes is a good value. That is what makes a captured request useless later: the timestamp is part of what is signed, so it cannot be moved forward.
  4. Compute HMAC-SHA256 over t, a dot and the raw body, and compare it to v1 in constant time.
  5. Answer with a 2xx status. A redirect is not followed and counts as failed.

The delivery id in X-NetLock-Delivery repeats when a signed webhook is delivered again, with a new t and a new signature. Use it to detect duplicates.

C#

using System.Linq;
using System.Security.Cryptography;
using System.Text;

static bool Verify(string secret, string? header, byte[] raw_body, int tolerance_seconds = 300)
{
    if (header == null)
        return false;

    string? t = null;
    string? v1 = null;

    foreach (string part in header.Split(','))
    {
        if (part.StartsWith("t="))
            t = part.Substring(2);
        else if (part.StartsWith("v1="))
            v1 = part.Substring(3);
    }

    if (t == null || v1 == null || !long.TryParse(t, out long timestamp))
        return false;

    if (Math.Abs(DateTimeOffset.UtcNow.ToUnixTimeSeconds() - timestamp) > tolerance_seconds)
        return false;

    byte[] message = Encoding.ASCII.GetBytes(t + ".").Concat(raw_body).ToArray();
    byte[] hash = HMACSHA256.HashData(Encoding.UTF8.GetBytes(secret), message);
    byte[] expected = Encoding.ASCII.GetBytes(Convert.ToHexString(hash).ToLowerInvariant());

    return CryptographicOperations.FixedTimeEquals(expected, Encoding.ASCII.GetBytes(v1));
}

In ASP.NET Core, read the body with request.BodyReader or copy request.Body into a MemoryStream, and do not bind it to a model first.

Python

import hashlib
import hmac
import time


def verify(secret: str, header: str | None, raw_body: bytes, tolerance_seconds: int = 300) -> bool:
    if not header:
        return False

    parts = dict(part.split("=", 1) for part in header.split(",") if "=" in part)
    t, v1 = parts.get("t"), parts.get("v1")

    if not t or not v1 or not (t.isascii() and t.isdigit()) or len(t) > 12:
        return False

    if abs(time.time() - int(t)) > tolerance_seconds:
        return False

    expected = hmac.new(secret.encode(), t.encode() + b"." + raw_body, hashlib.sha256).hexdigest()

    return hmac.compare_digest(expected.encode(), v1.encode())

In Flask the raw body is request.get_data(), in FastAPI await request.body().

Node.js

const crypto = require("crypto");

function verify(secret, header, rawBody, toleranceSeconds = 300) {
  if (!header) return false;

  const parts = Object.fromEntries(
    header.split(",").map((part) => [part.slice(0, part.indexOf("=")), part.slice(part.indexOf("=") + 1)])
  );
  const { t, v1 } = parts;

  if (!/^\d+$/.test(t ?? "") || !v1) return false;
  if (Math.abs(Date.now() / 1000 - Number(t)) > toleranceSeconds) return false;

  const body = Buffer.isBuffer(rawBody) ? rawBody : Buffer.alloc(0);
  const expected = crypto.createHmac("sha256", secret).update(`${t}.`).update(body).digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(v1);

  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

rawBody is a Buffer. In Express, use express.raw({ type: "*/*" }) on the route instead of express.json(). For a request without a body express.raw does not hand over a Buffer, which the routine treats as the empty body.

X.10.4 The secret

  • NetLock RMM generates the secret, in the form whsec_…. It cannot be chosen.
  • It is stored encrypted and shown once: when the subscription is created, when Sign requests is switched on, and after a rotation. Copy it at that moment. It cannot be read again later, not even by an administrator.
  • Rotating replaces it at once. Everything sent after the rotation is signed with the new secret, and the old one no longer verifies, so update the receiver right away.
  • With Sign requests switched off and saved, the secret is deleted. Switching on again generates a new one.
  • A webhook that signs never goes out unsigned. If the instance cannot read its secret, for example because the web console and the server use different encryption keys, nothing is sent and the failure is logged.
  • X-NetLock-Signature is reserved. The dialogs and the Public API refuse custom headers with that name.
  • A test from a dialog uses what is in the form. It signs with the stored secret only if the address equals the saved one; for another address it uses a one-time secret, which the receiver cannot verify, and says so. Every such test is recorded in the audit log, with the host of the target only.

X.10.5 Managing signed webhooks in the web console

Settings → Integrations → Signed webhooks needs the permission settings_integrations_enabled to read and settings_integrations_manage to change. A subscription appears only for accounts that cover every tenant it delivers, and only tenants of the account can be selected. Subscriptions created through the Public API appear here as well. Accounts that can only read see the scheme, host and port of an address, because path and query often carry a token.

  • Address. The address has to be absolute, http or https, without a user name or password. A cloud instance delivers to public addresses only, a self-hosted instance also to private ones. Neither delivers to loopback, link-local or metadata addresses. The address is checked when you save and again at every delivery.
  • Events. All seven event types of X.9.23, or all events, which also includes types added later.
  • Location limit. Without a selection, every location of the selected tenants is delivered. With a limit, whatever has no location is not delivered: website monitors, alerts of a whole tenant and removed devices. A subscription with a limit stays limited: if no location of the limit remains, because locations were deleted or their tenant was removed from the subscription, saving is refused until you choose another one. To deliver every location, delete the subscription and create it again.
  • Smaller reach. When a tenant leaves a subscription or its location limit shrinks, deliveries that are waiting or failed are dropped, because they can contain data the subscription no longer covers. They stay in the delivery log as failed.
  • Minimum severity. Applies to event.created only.
  • Active. A subscription starts at the present and does not replay older events. After 20 failed attempts in a row NetLock RMM switches it off and marks it. Switching it on again continues from the present.
  • Test. Sends a signed webhook.test delivery at once and reports the answer of the receiver. A test appears in the delivery log, but does not count as a failed attempt. An account can send six tests per minute. While the Public API is off, no test goes out.
  • Delivery log. Shows status, HTTP code, attempts and the reason of a failure. Send again puts a failed delivery back on the queue; the server sends the stored body within a few seconds with a new signature and the same delivery id. It needs an account that covers every tenant of the subscription, including any tenant deleted since then. A failed test is repeated with Test. The log follows the retention set under Settings → Retention, 14 days by default.

The Public API has to be switched on for deliveries to go out; the page says so when it is off.