Use the procedures on this page to create an alert channel, test it, and create a rule that sends alert events to it. You can then use the Event History page to review delivery attempts and diagnose failures.
This feature is available through Early Access. Enable on the Administration > Early Access Features page to access it.
Before you begin
Ensure you have the necessary permissions and prerequisites in place before configuring webhooks:- You have a BloodHound Enterprise account with the Administrator role.
- You have prepared a receiver that accepts HTTPS POST requests and validates BloodHound Enterprise HMAC signatures.
- Your receiver returns a 2xx response after it accepts an event.
- You have a secure location to store the HMAC secret. BloodHound Enterprise generates a secret for each webhook and displays it only when you create or rotate the webhook.
Create a webhook
Webhooks in BloodHound Enterprise are reusable configurations. Multiple rules can send alert events to the same webhook.We’ll cover how to configure rules that connect event triggers to webhooks later in this procedure. For now, focus on creating a webhook and verifying that your receiver can accept events.
1
Open Delivery
Go to Administration > Alerts > Delivery.
2
Create the webhook
Click Create and enter the following configuration details:
3
Store the HMAC secret
Click Create and copy the HMAC secret from the confirmation dialog.BloodHound Enterprise uses the secret to sign alert event requests sent to your receiver. Store the secret in your secret manager before you close the dialog.
BloodHound Enterprise does not display this secret again. If you lose it, regenerate the secret and update your receiver.
4
Complete webhook configuration
Click Close to return to the Delivery page or click View Webhook to see the webhook’s details.
Test a webhook
Use Run Test from the webhook’s actions menu before you create a production rule. The test sends a sample alert event to the webhook URL.Use the webhook contract reference to validate the headers, payload, and signature.
1
Open Run Test
On the Delivery page, click the ellipsis menu () for the webhook in the Action column and select Run Test.
2
Select the event
In the Run Test dialog, select the Collector Offline event trigger and version 1.
The version identifies the webhook payload contract for the event type. BloodHound Enterprise can add a newer contract version without changing the version used by an existing rule, so your receiver can continue processing the current contract until you update it.
3
Run the test
Click Run.
4
Confirm delivery
Confirm that your receiver accepted the signed request and proceed to the next section to create a rule.
If your receiver rejects or cannot receive the request, use the reported status code and error to diagnose the receiver.
Create a rule
Rules allow you to define which event types BloodHound Enterprise sends to which webhook configurations. When BloodHound Enterprise generates a matching event, it sends the alert event to the selected webhook URL.1
Open Rules
Go to Administration > Alerts > Rules.
2
Create a rule
Click Create and enter the following configuration details:
3
Complete rule configuration
Click Create to save the rule and return to the Rules page.BloodHound Enterprise sends the alert event to the selected webhook when it generates an event that matches the rule.
Manage webhooks and rules
The Actions column on the Delivery and Rules pages provides options for managing existing webhook and rule configurations. The column includes Edit and Delete options. Click the ellipsis () to access more actions.Manage webhooks
You can perform the following actions on a webhook:See Webhook health for how BloodHound Enterprise calculates and displays health and when it automatically disables a webhook.
Manage rules
You can perform the following actions on a rule:Disable a webhook or rule
You may need to temporarily disable a webhook or rule to pause deliveries while you perform maintenance, troubleshoot issues, or review configurations. Choose the action that matches the scope of the pause:Disabled rules and webhooks are excluded from new deliveries and scheduled retries. Disabling does not cancel a request that is already in progress.Failed delivery attempts remain in Event History and can resume retrying after you re-enable the associated rule or webhook. BloodHound Enterprise does not automatically deliver events that occur while the rule or webhook is disabled.
Webhook health
BloodHound Enterprise represents webhook health as a rolling score from0 to 1, where 1.0 is fully healthy. The API returns this value in the webhook’s health field. Each webhook starts with a health score of 1.0.
BloodHound Enterprise calculates the score as an exponentially weighted moving average of dispatch results. Each result has a weight of 0.1: successful dispatches increase the score and failed dispatches decrease it.
The Delivery page displays the score as a color-coded percentage badge in the Health column. The Webhook Details view displays the same badge. A score of 0.9 or higher is green, a score from 0.7 to less than 0.9 is yellow, and a score below 0.7 is red. For example:
- 90% indicates a healthy webhook.
- 80% indicates a webhook that has experienced some failed deliveries.
- 60% indicates a webhook that has experienced many failed deliveries.
0.5, which occurs after roughly seven consecutive failed dispatches. Health changes only after production dispatches; test requests do not affect the score. Review and correct the receiver before you re-enable the webhook. Re-enabling the webhook resets its health score to 1.0.
Automate configuration
Use the Alerts API in BloodHound Enterprise to manage webhooks, rules, event types, and attempts programmatically.- Webhook API endpoints
- Alert rule API endpoints
- Event type API endpoint
- Delivery attempt API endpoints
The create and rotate responses return the HMAC secret once; subsequent reads do not return it.