Guide to Auvik Webhooks: Features and Best Practices

Auvik webhooks carry network alerts out of Auvik: a firewall goes offline, an interface errors, a device comes back, and Auvik notifies your endpoint when the alert is triggered and again when it clears. If you're an MSP or IT team monitoring networks with Auvik, the webhook integration is how those alerts reach a system Auvik has no built-in integration for.

This guide covers how to set up Auvik's webhook integration, which authentication method to choose, the alert notification format, and the practices that keep an Auvik receiver reliable.

What are Auvik webhooks?

Auvik's generic Webhook integration sends alert notifications to a URL. Notifications are sent "when an alert associated with the webhook notification channel has been either triggered or cleared", as JSON. You decide which alerts go to the integration through a notification channel. Webhook integrations are managed from the MSP dashboard only.

Auvik doesn't sign notifications. The integration offers four authentication methods: No Authentication, Header ("an API key is provided through a custom HTTP header", with a Key and Value you enter), Basic Authentication, and OAuth 2.0 client credentials. For a receiver you build, Header is the simplest to check: Auvik sends the same key and value on every request, and your receiver compares them.

Auvik webhook features

Feature	Details
Configuration	MSP dashboard: Integrations > Add Integration > Webhook
Alert routing	A notification channel mapped to the alerts you want sent
When it fires	When an alert is triggered or cleared
Format	JSON, or your own shape with a JSONata expression
Event identifier	alertStatusString (Triggered or Cleared), plus alertName
Authentication	No Authentication, Header, Basic, or OAuth 2.0 client credentials. No signature
Extra headers	Optional additional key/value headers
URL	HTTPS required
Retries, timeout and method	Not documented
Source IPs	Not published

Common events

There are two notification types, triggered and cleared. Which alert fired is in alertName, and alerts are defined in your Auvik account. Here is Auvik's triggered example:

{
  "entityId": "MTI3Mzg5NDYxMjM5NzQsNDczNjQ5ODI3NjQ3OTI=",
  "subject": "You have a new alert!",
  "alertStatusString": "Triggered",
  "alertId": "MTI3Mzg5NDYxMjM5NzQsNTI4NzY0OTgyNzM2NA==",
  "alertName": "Firewall is online (webhook)",
  "entityName": "Auvik's SonicWall 2400",
  "companyName": "Nanook",
  "entityType": "device",
  "date": "2016-11-15T15:39:13.719Z",
  "link": "https://nanook.my.auvik.com/alert/193884525816632836/summary",
  "alertStatus": 0,
  "alertDescription": "Firewall is online (webhook)",
  "alertSeverityString": "Emergency",
  "alertSeverity": 1,
  "companyId": "191992599575398404",
  "correlationId": "MTI3Mzg5NDYxMjM5NzQsNTI4NzY0OTgyNzM2NA=="
}

Field	Meaning
alertStatusString, alertStatus	Triggered (0) or Cleared (1)
alertSeverityString, alertSeverity	Emergency (1), Critical (2), Warning (3) or Info (4)
alertId, alertName, alertDescription	The alert's API ID, name and description
entityId, entityName, entityType	The asset that triggered the alert: a device, interface, network or service
companyId, companyName	The site the asset is in
correlationId	The alert trigger's API ID, usable to dismiss the alert through the Auvik API
date	When the event was detected, in UTC
link, subject	A link to the alert in Auvik, and the notification subject

The IDs are the same ones the Auvik APIs use. In Auvik's examples, the triggered and cleared notifications for the same alert have different alertId values but the same correlationId, so pair a clear with its trigger on correlationId. Unlike Auvik's other integrations, date is always UTC rather than your dashboard's time zone.

Setting up Auvik webhooks

1. Generate a long random secret, for example with openssl rand -hex 32.
2. In the MSP dashboard, click Integrations, hover over Add Integration and select Webhook.
3. Enter an Integration name and your HTTPS endpoint as the Webhook URL.
4. Choose Header as the authentication method and enter the Key and Value, for example Authorization and Bearer <secret>.
5. Leave the JSONata expression empty unless the receiver needs a different shape.
6. Click Test Connection, then Save.
7. Create a notification channel for the integration and map it to the alerts you want sent.

All alerts on an integration feed a single webhook. To send different alerts to different URLs, create an integration per URL. Auvik also notes that organisation names need standard English characters, or webhook alerts don't behave as expected.

In Hookdeck. Choose Header authentication on the Auvik webhook, not OAuth. Create a source with the Auvik type, enter the Key in API Key Header and the exact Value in API Key, including any Bearer prefix, and use the source URL as the Webhook URL. Hookdeck matches the name case-insensitively and the value exactly. The source accepts POST, and doesn't check Basic Authentication or OAuth 2.0.

For local development, hookdeck listen 3000 auvik --path /webhooks/auvik with the Hookdeck CLI gives you a public HTTPS URL, with no account required.

Securing Auvik webhooks

Look up the header by its Key and compare the whole value with the secret in constant time.

const crypto = require('crypto');
const express = require('express');

const app = express();

function safeEqual(received, expected) {
  const a = Buffer.from(received, 'utf8');
  const b = Buffer.from(expected, 'utf8');
  // timingSafeEqual throws on buffers of different lengths
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

app.post('/webhooks/auvik', express.raw({ type: '*/*' }), (req, res) => {
  const secret = process.env.AUVIK_WEBHOOK_SECRET; // the exact header value
  if (!secret) return res.sendStatus(500); // fail closed when unconfigured

  const name = process.env.AUVIK_WEBHOOK_HEADER || 'Authorization'; // the Header Key
  const received = req.get(name); // case-insensitive lookup
  if (typeof received !== 'string' || !safeEqual(received, secret)) {
    return res.sendStatus(401);
  }

  let alert;
  try {
    alert = JSON.parse(req.body.toString('utf8'));
  } catch {
    return res.sendStatus(400);
  }

  // Queue the alert. Open on Triggered, resolve on Cleared, keyed on correlationId.
  res.sendStatus(200);
});

The same check in Python:

import hmac
import os


def verify_auvik_request(headers) -> bool:
    secret = os.environ.get("AUVIK_WEBHOOK_SECRET")
    if not secret:
        return False  # fail closed
    name = os.environ.get("AUVIK_WEBHOOK_HEADER", "Authorization")
    received = headers.get(name)  # case-insensitive in Starlette and Flask
    if not received:
        return False
    return hmac.compare_digest(received.encode("utf-8"), secret.encode("utf-8"))

A matching header proves the sender knows the value. It doesn't prove the alert is unchanged, and a captured notification can be replayed later, because nothing is signed. Use HTTPS, which Auvik requires anyway, and a long random value, and rotate it in the integration and your receiver if it may have leaked.

Make Auvik webhooks production-ready. Hookdeck Event Gateway checks your Header authentication value on every Auvik alert, stores each notification durably, and retries delivery to your on-call or ticketing service on a schedule you control.

Auvik webhook limitations and pain points

Delivery behaviour isn't documented

The Problem: You can't tell whether an alert sent while your endpoint was down will arrive later.

Why It Happens: Auvik's articles cover setup, Test Connection and troubleshooting, but not retries, timeouts or which responses count as success.

Workarounds:

• Keep the endpoint highly available and respond with a 2xx quickly.
• After an outage, check open alerts in Auvik and reconcile.

How Hookdeck Can Help: Hookdeck accepts each alert as it arrives, so your service's downtime doesn't depend on Auvik retrying. Hookdeck then retries delivery to your service and lets you replay any alert.

Trigger and clear need pairing

The Problem: Tickets opened for triggered alerts never close, or a clear arrives for a ticket you can't find.

Why It Happens: Each state change is a separate notification. In Auvik's examples the two notifications share a correlationId but not an alertId, and a clear can arrive before its trigger if one delivery is delayed.

Workarounds:

• Key open incidents on correlationId, and confirm that pairing on your first real triggered and cleared alerts.
• If a clear arrives first, record it so a late trigger doesn't reopen the incident.

How Hookdeck Can Help: Every notification is stored in Hookdeck with its body, so you can search by correlationId and see both halves of an alert's life, and replay them in order after fixing your logic.

JSONata changes the contract

The Problem: A teammate adds a JSONata expression to suit a third-party API, and your receiver starts rejecting notifications.

Why It Happens: The expression replaces Auvik's documented body with whatever shape it produces.

Workarounds:

• Leave the expression empty on integrations that feed your own receiver.
• If you do transform, version the shape and validate it.

How Hookdeck Can Help: Hookdeck transformations can reshape notifications per destination, so Auvik can keep sending its standard body and each consumer gets the shape it needs.

Only Header authentication fits a simple receiver

The Problem: An integration set up with OAuth 2.0 or Basic Authentication doesn't verify in Hookdeck's Auvik source.

Why It Happens: OAuth 2.0 client credentials need a token endpoint that Auvik calls first, and Hookdeck's Auvik source checks the Header method only.

Workarounds:

• Choose Header, with a long random value.
• Use Additional HTTP headers for non-secret context, such as which integration sent the alert.

How Hookdeck Can Help: Hookdeck's Auvik source compares the header you name with the exact value you enter. Hookdeck answers Auvik with a 200 either way, then records a request without the right header as failed verification, so it never reaches your destination.

Best practices

Route on severity and status

Use alertSeverity to decide who gets paged and alertStatusString to open or resolve. Treat unknown values as the most severe.

Deduplicate deliveries

Build a key from alertId, alertStatusString and date, and skip repeats. See our guide to webhook idempotency.

Map alerts deliberately

The notification channel decides what reaches the webhook. Send only alerts someone will act on, so the receiving system isn't flooded.

Acknowledge fast and process asynchronously

Verify, store, respond with 200, then create the ticket or page. See why to process webhooks asynchronously.

Conclusion

Auvik sends a flat JSON notification when an alert mapped to the webhook's notification channel is triggered or cleared, and Header authentication is the credential to check. Compare the header in constant time over HTTPS, pair triggers and clears on correlationId, route on severity, and keep the standard body unless you have a reason to transform it.

Hookdeck Event Gateway sits in front of your receiver, checks the header, keeps every alert, and retries delivery to your service, which covers the delivery behaviour Auvik doesn't document.

Get started with Hookdeck for free and handle Auvik webhooks reliably in minutes.