Guide to Huntress Webhooks: Features and Best Practices
Huntress webhooks deliver notifications from the Huntress Portal to an endpoint you control. If you use Huntress for managed endpoint detection and response, webhooks are how new incident reports, escalations and account notices reach your ticketing system, chat channels or security tooling without polling the Huntress API.
Huntress documents its webhooks briefly, so this guide is short. It covers how to add an endpoint, how deliveries are signed, what Huntress tells you about the payload, and what to do about the gaps.
What are Huntress webhooks?
A Huntress webhook endpoint is an HTTPS URL you add in the Portal, with toggles for the notification categories it should receive. When a subscribed event happens, Huntress sends an HTTP POST with a JSON payload describing the event.
Huntress uses Svix to sign deliveries. Each request carries a signature, a timestamp and a unique delivery ID in three headers, and Huntress says any Svix client library verifies them. Huntress's article doesn't name the headers. Testing shows the Standard Webhooks names webhook-signature, webhook-timestamp and webhook-id are used.
Huntress webhook features
| Feature | Details |
|---|---|
| Who can configure | Account admins |
| Configuration | Integrations > Add an Integration > Webhooks, then Add Endpoint |
| Endpoints | Up to 5 per account, HTTPS only |
| Categories | Incident Reports, Escalations, Platform Actions, Account Notices, toggled per endpoint |
| Signature headers | webhook-id, webhook-timestamp, webhook-signature or svix-id, svix-timestamp, svix-signature |
| Scheme | Svix (Standard Webhooks): HMAC-SHA256, base64, entries prefixed with v1, |
| Signed content | {id}.{timestamp}.{raw body} |
| Secret | Per endpoint, whsec_ prefix, from View Signing Secret in the endpoint's menu |
| Testing | Send Test in the endpoint's menu |
| Delivery log | View Delivery Attempts, including request and response bodies |
Huntress doesn't publish the payload schema, event type names, a retry schedule, a response timeout or source IPs.
Notification categories
An endpoint subscribes to any of four categories: Incident Reports, Escalations, Platform Actions and Account Notices.
These are toggles on the endpoint, not values you can rely on in the body. Huntress describes the body only as "a JSON payload describing the event" and doesn't publish its fields. To see the real shape, send a test from the endpoint's menu, then open View Delivery Attempts and select View on an attempt to read its request body. Write your routing against what you see there, and handle anything unrecognised by logging it.
The test delivery we received had a webhook-test: true header and this body:
{
"event_type": "test.event",
"message": "Hello World"
}
Setting up Huntress webhooks
You need the account admin role.
- From the menu at the top right of the Huntress dashboard, choose Integrations.
- Click Add an Integration and choose Webhooks, under Notifications.
- Click Add Endpoint, enter an HTTPS URL, and toggle on the categories this endpoint should receive.
- Save.
- From the endpoint's three-dot menu, choose View Signing Secret and store the secret server-side, for example as
HUNTRESS_WEBHOOK_SECRET. - Choose Send Test from the same menu to check delivery.
Huntress's own page doesn't show the secret, but the value under View Signing Secret is a Svix secret that starts with whsec_. Copy the whole value, prefix included.
If you use Hookdeck, create a source with the Huntress source type, paste the whole signing secret into it, and use the Hookdeck source URL as the endpoint URL. Hookdeck verifies the signature whichever header prefix Huntress uses.
Securing Huntress webhooks
Huntress points to Svix's verification guide. To verify manually, join the delivery ID, the timestamp and the raw request body with dots. Take the part of the secret after whsec_, base64-decode it, and use the bytes as the HMAC-SHA256 key. Encode the result as base64 and compare it in constant time with each v1, entry in the space-delimited signature header. A match on any entry is enough.
Read each header under either prefix. A handler that only looks for the svix-* names from Svix's guide rejects the webhook-* test delivery we received from Huntress.
Huntress names no timestamp tolerance. The check below is optional and off by default. If you turn it on, remember that a delivery replayed later, for example from Hookdeck, keeps its original timestamp.
const crypto = require('crypto');
const express = require('express');
// Svix's guide says svix-*, but a live test delivery used webhook-*. Accept either.
const header = (headers, name) => headers[`webhook-${name}`] ?? headers[`svix-${name}`];
function verifyHuntressSignature(rawBody, headers, secret, toleranceSeconds = 0) {
const id = header(headers, 'id');
const timestamp = header(headers, 'timestamp');
const signatureHeader = header(headers, 'signature');
if (!id || !timestamp || !signatureHeader || !secret || !secret.startsWith('whsec_')) return false;
if (!/^\d+$/.test(timestamp)) return false;
// Optional replay check, off by default.
if (toleranceSeconds > 0 && Math.abs(Date.now() / 1000 - Number(timestamp)) > toleranceSeconds) {
return false;
}
const key = Buffer.from(secret.slice('whsec_'.length), 'base64');
const expected = crypto
.createHmac('sha256', key)
.update(`${id}.${timestamp}.`)
.update(rawBody)
.digest();
return signatureHeader.split(' ').some((entry) => {
const [version, signature] = entry.split(',');
if (version !== 'v1' || !signature) return false;
const received = Buffer.from(signature, 'base64');
return received.length === expected.length && crypto.timingSafeEqual(received, expected);
});
}
const app = express();
app.post('/webhooks/huntress', express.raw({ type: '*/*' }), (req, res) => {
if (!verifyHuntressSignature(req.body, req.headers, process.env.HUNTRESS_WEBHOOK_SECRET)) {
return res.sendStatus(401);
}
const event = JSON.parse(req.body.toString('utf8'));
console.log('Huntress delivery', header(req.headers, 'id'), event.event_type); // Correlate with View Delivery Attempts.
// Queue the event for processing, then acknowledge.
res.sendStatus(200);
});
The same check in Python:
import base64
import binascii
import hashlib
import hmac
import time
def header(headers, name: str):
# Svix's guide says svix-*, but a live test delivery used webhook-*. Accept either.
return headers.get(f"webhook-{name}") or headers.get(f"svix-{name}")
def verify_huntress_signature(raw_body: bytes, headers, secret: str, tolerance_seconds: int = 0) -> bool:
msg_id = header(headers, "id")
timestamp = header(headers, "timestamp")
signature_header = header(headers, "signature")
if not (msg_id and timestamp and signature_header and secret and secret.startswith("whsec_")):
return False
if not timestamp.isdigit():
return False
# Optional replay check, off by default.
if tolerance_seconds > 0 and abs(time.time() - int(timestamp)) > tolerance_seconds:
return False
try:
key = base64.b64decode(secret[len("whsec_"):])
except (binascii.Error, ValueError):
return False
signed = f"{msg_id}.{timestamp}.".encode("utf-8") + raw_body
expected = base64.b64encode(hmac.new(key, signed, hashlib.sha256).digest())
for entry in signature_header.split(" "):
version, _, signature = entry.partition(",")
if version == "v1" and hmac.compare_digest(signature.encode("utf-8"), expected):
return True
return False
# In FastAPI: raw_body = await request.body()
# verify_huntress_signature(raw_body, request.headers, os.environ["HUNTRESS_WEBHOOK_SECRET"])
The Svix client libraries that Huntress recommends do the same check and accept either header prefix, so you can pass them the request headers as they are. They always enforce a five-minute timestamp window, though. A delivery that Hookdeck retries or replays more than five minutes after Huntress sent it fails the library's check even though its signature is valid. The Huntress webhook skill includes a manual verifier where you can drop or widen the window.
Make Huntress webhooks production-ready. Hookdeck Event Gateway verifies the Svix signature on every Huntress delivery, keeps each security notification with its full body, and delivers it to your ticketing and alerting tools on a schedule you control.
Huntress webhook limitations and pain points
No published payload or event types
The Problem: You have to write a handler without knowing what the body looks like.
Why It Happens: Huntress lists four categories but doesn't document the JSON body, or any field that names the event.
Workarounds:
- Send a test and read the request body under View Delivery Attempts before you write parsing code.
- Treat every field as optional, and log and acknowledge bodies you don't recognise instead of failing them.
How Hookdeck Can Help: Hookdeck stores the headers and body of every request, so you can collect real examples of each category and replay them against your handler while you build it.
Unknown retry behaviour
The Problem: You can't tell whether a notification missed during an outage will be sent again.
Why It Happens: Huntress publishes no retry schedule or timeout. It asks you to respond fast and keep a log of delivery IDs.
Workarounds:
- Return
200as soon as the request is verified and queued, as Huntress recommends. - Check View Delivery Attempts after any incident on your side.
How Hookdeck Can Help: Hookdeck accepts each delivery as soon as it arrives, then delivers to your service with retries you configure, so an outage on your side doesn't depend on Huntress's unpublished policy.
Five endpoints per account
The Problem: You want separate endpoints for several tools or customers, and run out.
Why It Happens: Huntress allows up to 5 endpoints per account.
Workarounds:
- Use one endpoint per purpose and fan out inside your own receiver.
How Hookdeck Can Help: One Huntress endpoint pointing at Hookdeck can feed as many destinations as you need, each with its own filters.
Best practices
Verify against the raw body
Huntress's first gotcha is to verify against the raw body, because re-serialising parsed JSON breaks the HMAC. Use express.raw({ type: '*/*' }) in Express, await request.text() in Next.js and await request.body() in FastAPI.
Log the delivery ID
Log the delivery ID (webhook-id, or svix-id) with every request, as Huntress suggests, so you can match it with View Delivery Attempts when a notification goes missing.
Deduplicate on the delivery ID
Under the Svix scheme, the delivery ID identifies the message, so use it to skip repeats. See our guide to webhook idempotency.
Acknowledge fast and process asynchronously
Verify, enqueue the work, return 200. Don't open tickets or call other APIs inside the request. See why to process webhooks asynchronously.
Conclusion
Huntress sends Portal notifications as JSON POST requests signed by Svix. Verify the signature header (webhook-signature in our test, svix-signature in Svix's guide) against the raw body, log the delivery ID, respond quickly, and build your parser from real deliveries, because Huntress doesn't publish the payload.
Hookdeck Event Gateway verifies every Huntress signature and keeps each notification until your tools have processed it, so a security alert isn't lost to an outage on your side.
Get started with Hookdeck for free and handle Huntress webhooks reliably in minutes.