# 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:

```json
{
  "event_type": "test.event",
  "message": "Hello World"
}

```

## Setting up Huntress webhooks

You need the account admin role.

1. From the menu at the top right of the Huntress dashboard, choose **Integrations**.
2. Click **Add an Integration** and choose **Webhooks**, under Notifications.
3. Click **Add Endpoint**, enter an HTTPS URL, and toggle on the categories this endpoint should receive.
4. Save.
5. From the endpoint's three-dot menu, choose **View Signing Secret** and store the secret server-side, for example as `HUNTRESS_WEBHOOK_SECRET`.
6. 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.

```javascript
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:

```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](https://github.com/hookdeck/webhook-skills/tree/main/skills/huntress-webhooks) includes a manual verifier where you can drop or widen the window.

> **Make Huntress webhooks production-ready.** [Hookdeck Event Gateway](/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 `200` as 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](/docs/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](/docs/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](/webhooks/guides/implement-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](/webhooks/guides/why-implement-asynchronous-processing-webhooks).

## 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](https://hookdeck.com) 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](https://dashboard.hookdeck.com/signup) for free and handle Huntress webhooks reliably in minutes.