Alert Webhook Contract

BloodHound Enterprise sends signed HTTPS POST requests to configured alert webhooks.

This feature is available through Early Access. Enable on the Administration > Early Access Features page to access it.

This page documents the general webhook contract and the event-specific contracts currently supported. Use it to validate requests, route events, and process deliveries safely.

General webhook contract

The webhook contract defines how BloodHound Enterprise sends, signs, and retries alert events. The event-specific contract below defines the trigger and the contents of the event payload.

Receive the request

BloodHound Enterprise sends a JSON request with the following headers:

Header	Purpose
`Content-Type: application/json`	Identifies the request body format.
`X-Bloodhound-Signature`	Carries the signature timestamp and HMAC-SHA256 signature.
`X-Bloodhound-Event-Type`	Lets your receiver route the alert event without parsing the body.
`X-Bloodhound-Event-ID`	Identifies the alert event for idempotent processing.

Return a 2xx response after your receiver accepts the event. BloodHound Enterprise treats every other HTTP status, including redirects, as a failed delivery.

Event envelope

The envelope stays stable across event versions. The version field identifies the shape of the data object. The following example shows the common envelope. The event_type, version, and data values depend on the event-specific contract:

{
  "event_id": "018f0e7b-60d6-7b9d-8f4a-2b8f68eb4aa0",
  "event_type": "example.event",
  "version": 1,
  "timestamp": "2026-08-28T14:17:00Z",
  "message": "Human-readable summary for the event.",
  "data": {
    "event_specific_field": "event-specific value"
  }
}

UUID

required

Stable alert event identifier. It matches X-Bloodhound-Event-ID and is used to deduplicate deliveries.

string

required

Alert event type identifier. Use it to route the event.

integer

required

Payload data version. The event-specific contract defines the shape of the data object for each version.

RFC 3339 timestamp

required

Time BloodHound Enterprise created the alert event.

string

required

Human-readable summary.

object

required

Event-specific details.

Verify the signature

BloodHound Enterprise signs the exact raw request body with your alert webhook’s HMAC secret. The signature header uses the following format:

t=<unix-timestamp>,v1=<hex-hmac-sha256>

The signed value is the timestamp, a period, and the unmodified request body:

HMAC-SHA256(secret, "{t}.{raw body}")

Do not parse and reserialize JSON before verification. That changes the body and invalidates the signature.

Delivery behavior

Behavior	Value
Request method	HTTPS POST
Success response	Any 2xx HTTP response
Request timeout	7 seconds
TLS requirement	TLS 1.2 or later
Automatic retries	Up to seven total attempts: the initial delivery and up to six retries
Retry timing	The first retry is scheduled after up to about six minutes. Later retries use a 4x backoff with up to 20% subtract-only jitter. The retry worker runs about every six minutes.
Retry processing	The retry worker processes up to 30 due deliveries per run. A backlog can delay a retry beyond its scheduled time.
Event History retention	Events and their delivery attempts are retained for 90 days.

BloodHound Enterprise treats a delivery as failed when the request times out, encounters a transport or TLS error, or returns a non-2xx response. Failed deliveries are retried according to the table and dead-lettered after the final failed attempt. Use the Event History page or the retry attempt API to requeue a failed delivery. A manual requeue gives it one additional send attempt. Retries and manual requeues can deliver the same event more than once. Use event_id to deduplicate events and make processing idempotent. Retries retain the event ID and payload timestamp but receive a new signature timestamp. Delivery order is not guaranteed. Initial deliveries and retries run independently, so events can arrive out of order. Use the event timestamp for context, not the arrival time. BloodHound Enterprise does not enforce a replay-timestamp tolerance. The examples reject signatures whose t value differs from the receiver’s clock by more than five minutes. Set and enforce an appropriate window in your receiver. Return a 2xx response only after your receiver has accepted the event for processing. If your receiver cannot accept the event, return a non-2xx response so BloodHound Enterprise can record the failure and retry it when eligible.

Collector Offline event contract

Alert event	Identifier	Data version	Trigger
Collector Offline	`collector.status.offline`	`1`	A collector has not checked in for at least 20 minutes.

BloodHound Enterprise evaluates collector status about every seven minutes. It suppresses another alert event for the same collector for seven days and does not issue a recovery event.

Payload version 1

The following example shows the general event envelope with the Collector Offline data object:

{
  "event_id": "018f0e7b-60d6-7b9d-8f4a-2b8f68eb4aa0",
  "event_type": "collector.status.offline",
  "version": 1,
  "timestamp": "2026-08-28T14:17:00Z",
  "message": "Collector example-collector may be offline. Last checkin time: 2026-08-28T13:55:00Z",
  "data": {
    "collector_id": "07165367-2977-4fdf-8b4f-6bff3bfe62f3",
    "name": "example-collector",
    "hostname": "collector01.example.test",
    "ip_address": "192.0.2.10",
    "type": "sharphound",
    "version": "2.15.0",
    "last_checkin": "2026-08-28T13:55:00Z",
    "created_at": "2026-05-02T09:00:00Z",
    "updated_at": "2026-08-28T13:55:00Z",
    "auth_type": "bloodhound",
    "issuer_address": "https://bloodhound.example.test",
    "issuer_address_override": ""
  }
}

Version 1 includes the following fields in the data object. Every property is always present, non-null, and never omitted. An empty string or zero timestamp can appear when the corresponding database column has no value. These rules describe events generated by the current collector-offline producer.

UUID string

required

Stable collector identifier.

string

required

Collector name.

string

required

Collector host name.

string

required

Collector IP address.

string

required

Declared collector type: azurehound, sharphound, or openhound.

string

required

Collector software version.

RFC 3339 timestamp string

required

Collector’s last check-in time in RFC 3339 UTC format.

RFC 3339 timestamp string

required

Time the collector record was created.

RFC 3339 timestamp string

required

Time the collector record was last updated.

string

required

Declared collector authentication type: bloodhound or windows.

string

required

Collector issuer address.

string

required

Collector issuer address override. An empty string may indicate that no override is configured.

The event builder does not validate the declared collector type or authentication type against an enum.

The payload can include infrastructure and collector metadata. Protect the receiving endpoint, restrict who can access stored payloads, and do not send the payload to an unapproved third party.

Get Started with BloodHound

Install a Data Collector

Collect Data

OpenGraph

OpenHound

Analyze Attack Path Data

Manage BloodHound

API & Integrations

On-premises BloodHound Enterprise

Resources

Alert Webhook Contract

General webhook contract

Receive the request

Event envelope

Verify the signature

Delivery behavior

Collector Offline event contract

Payload version 1

​General webhook contract

​Receive the request

​Event envelope

​Verify the signature

​Delivery behavior

​Collector Offline event contract

​Payload version 1

General webhook contract

Receive the request

Event envelope

Verify the signature

Delivery behavior

Collector Offline event contract

Payload version 1