To allow the integration of Expel data without API polling, Expel can send webhook requests to external URLs.
Quick Links
Add a Webhook Integration
To subscribe to webhook notifications in Workbench, you need to add at least one webhook integration.
-
From the main menu, click Organization Settings > Integrations.
-
At the bottom of the page, click Add a webhook destination.
-
Enter a name for the webhook.
-
Enter the destination URL to send the webhook requests to.
-
Copy the secret key for the webhook and save it in a safe location.
Note
When you finish the process and click Add, you can't access this secret key again. -
Click Add.
Add a Notification Rule With a Webhook Destination
If at least one webhook integration exists, you can subscribe to notification rules where the destination is a webhook URL.
-
Add a new notification rule.
-
From the Notify Via section, select Webhook.
-
Select a webhook URL.
Webhook Data Model
The webhook body is UTF-8-encoded JSON.
The webhook JSON itself is a wrapper around an "event", which is a structure that provides all the contextual data around an action or change within Workbench. This object varies in overall structure but embeds a consistent series of representational Expel objects, for example, Investigation and RemediationAction.
-
guid: the unique ID for the main object associated with the webhook. -
rule: the name of the notification rule subscription that produced the webhook. -
event_name: the name of the event that triggered the rule. This name indicates the type of object provided in thedatakey. -
data: JSON object of the event emitted by Workbench.
{
"guid": "1a9c6d7a-78e6-4238-8cd7-8d2ec2492cab",
"rule": "<rule name>",
"event_name": "<event name>",
"data": {<event content>}
}
For a breakdown of what can be present in the data key, see Webhook Model Reference.
Webhook Signature
Every webhook sent by Expel contains the HTTP header Expel-Signature-256, formatted as sha256={some hash}. This header is a SHA-256 HMAC hex digest of the webhook payload bytes, generated using the secret key. The secret key is provided through Workbench when the webhook integration is created.
To verify that a webhook originated from Expel, calculate the HMAC signature using the secret key and compare it to the header.
Note
All webhook requests that Expel sends are encoded using UTF-8. The HMAC hex digest should be computed using the secret and webhook payload, both encoded as UTF-8.
Webhook POST Behavior
Your receiving server should respond to our webhook request with a valid status code indicating the result. Send the status code in the response header; a response body is unnecessary. The webhook responds to status codes as follows:
| Status Code | Result | Expel Action |
|---|---|---|
200 |
The server successfully receives the request. | The request is not retried. |
406 |
The server rejects the request. | The request is not retried. |
4xx5xx
|
The server can not process the request. |
The request is retried up to five times at the following intervals:
|
No further requests are made if Expel receives a 200 or 406 during a retry sequence.
Failure Handling
During your initial webhook setup, Expel checks for a successful connection from our webhook to your endpoint and automatically resolves test connection failures. After sending data to your endpoint, Expel support will share error information for failed responses and notify you of any required actions.
Expel cannot troubleshoot any issues with webhook processing by a customer’s receiving server or endpoint. We do not have the visibility or ability to fix these errors; we can only address internal errors. After the webhook request is sent successfully to your server and endpoint, please resolve any issues that prevent webhook communication.
Best Practices for Securing Webhooks
When setting up an HTTP server for consuming Expel webhooks, use the following best practices:
-
Ensure that the server always uses HTTPS and has a valid signed certificate.
-
Always verify the Expel-Signature-256 header sent with all valid requests.
-
Set a limit on requests per second and request size to prevent DOS.
It is unlikely that Expel webhooks will constitute a large volume of requests, but the server should be able to handle burst of requests.
-
Optionally, allowlist Expel's IP addresses to further limit unwanted traffic.