Skip to main content

How to use Webhooks Integration

Michael Vincent
  • Updated

Overview

Webhooks are HTTP callbacks that deliver real-time event notifications from the Huntress Portal to an endpoint you control. Instead of polling our API to ask "did anything change?", your endpoint receives a POST request whenever a subscribed event occurs.

Each delivery includes:

  • An HTTP POST to your configured URL
  • A JSON payload describing the event
  • Headers containing a Svix signature, a timestamp, and a unique delivery ID

You can subscribe to events in four categories: Incident Reports, Escalations, Platform Actions, and Account Notices.

Configuring a Webhook in the Portal

Webhook configuration lives under Integrations. You'll need to have the role of account admin to configure Webhooks.

  1. From the hamburger menu at the top right corner of the Huntress Dashboard, choose Integrations.
  2. Click Add an Integration and choose Webhooks (under Notifications). This lands you on the webhook Configure page. Note if you already have a Webhook configured you will see Webhook listed in the table of integrations
  3. Click Add Endpoint and provide:
    • A destination URL (must be HTTPS).
    • The notification categories you want this endpoint to receive (toggle each on or off).
  4. Save. You can have up to 5 endpoints per account.
  5. Use the three-dot menu (⋯) next to any endpoint to View Signing Secret, Send Test, View Delivery Attempts, or Delete it.

Verifying Signatures

Always verify the signature before acting on a payload. Without it, anyone who learns your endpoint URL can send forged events. Huntress uses Svix to sign Webhook payloads, so any Svix client library will work out of the box. Rather than rolling your own implementation, follow Svix's guide for language-specific libraries and code examples:

Verifying Webhooks - Svix Docs

Common Gotchas

  • Verify against the raw body, not the parsed JSON. Re-serializing changes whitespace and breaks the HMAC.
  • Respond fast. Verify, enqueue the work, return 200. Don't process inline.
  • Log delivery IDs so you can correlate with the Portal's View Delivery Attempts page when debugging missed events.

FAQ

How do I test notifications for the Webhook? 

  • Select the 3-dot ellipsis to the right of your Existing Endpoint, and choose Send Test. 

How do I view Delivery Attempts or logs?

  • Select the 3-dot ellipsis to the right of your Existing Endpoint, and choose View Delivery Attempts. It does take a moment to load the logs, and we've added a manual refresh button as well. 
  • Select View next to the attempt to view additional details, such as Request Body or Response Body. 

Related articles