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 webhooks | Webhook notification channel | Ticket webhooks | |
|---|---|---|---|
| Configured on | Settings → Integrations → Signed webhooks, or /v1/webhooks of the Public API | Settings → Notifications, Webhook tab (A.8.6) | Tickets → Departments, Manage Webhooks (Chapter 10.16) |
| Signed | Always | With the switch Sign requests, off by default | With the switch Sign requests, off by default |
| Method | POST | The configured method | The configured method |
| Body | The JSON envelope type, id, createdAt, data | The configured template after the placeholders were replaced; without a template a default JSON document with the event values | The configured template after the placeholders were replaced; without a template a default JSON document with the event values |
| Further headers | X-NetLock-Event, X-NetLock-Webhook-Id, X-NetLock-Delivery | The configured headers | The configured headers |
| Retries | Yes, with a growing delay | No | No |
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=cf7d053522b08300fae293c3bcbf4e183d4a9538620c18dc9a46d063337936fatis the time of the send in Unix seconds.v1is the lowercase hex HMAC-SHA256 of the exact stringt + "." + body, keyed with the secret as UTF-8 text.bodyis exactly what the request carries, as UTF-8. A request that carries no body, which is everyGETand 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
- 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.
- Split the header into
tandv1. - Reject the request if
tis 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. - Compute HMAC-SHA256 over
t, a dot and the raw body, and compare it tov1in constant time. - Answer with a
2xxstatus. 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 requestsis 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 requestsswitched 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-Signatureis 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,
httporhttps, 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.createdonly. - 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.testdelivery 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 againputs 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 withTest. The log follows the retention set underSettings → 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.
Related
- X.9 — Public API — webhook event types and the
/v1/webhooksendpoints. - A.8 — Notifications deep dive — the webhook notification channel.
- Chapter 10.16 — Webhooks — ticket webhooks.