The Webhook integration allows Expel to notify you about specific events via webhooks without requiring API polling. You can add destination URLs that leverage either a username and password authentication, or hash-based message authentication code (HMAC) header authentication. After you have added a webhook destination, you can then set up a variety of notifications that will send the desired data to it.

Prerequisites

1. You must have organization admin permissions in Workbench to add webhooks and set up notifications.
2. You must have sufficient understanding of webhooks, JSON objects, and one of the available webhook authentication methods (basic or HMAC).
3. You should be able to follow Expel's best practices (found in Step 1) when setting up or choosing a server to ensure the connection is secure.

Quick Links

1. How Expel's Webhook Integration Works
   • Webhook Data Model
   • Failure Handling
2. Step 1: Prepare Your Receiving Server
   • Implement Recommended Best Practices
   • Webhook Authentication
   • HTTP Response
3. Step 2: Add a New Webhook Destination
4. Step 3: Set Up the Notification

How Expel's Webhook Integration Works

Expel sends an HTTP POST request via a webhook to your HTTP server when an Expel event (that you specify) happens in Workbench. The HTTP request contains a payload formatted in JSON, with a maximum size of 10 MB (although in practice it will be much lower), which holds all of the data about the Workbench event. Your server must then respond with a status code to acknowledge receipt of the message so that we do not retry sending it.

Setting up a webhook in Workbench is a three-step process:

1. First, you must make sure your HTTP server is ready to accept the webhook request.
   • There are a few best practices for server setup that we recommend you utilize in order to secure your webhooks.
   • Your server must know where in the webhook request to find the authentication credentials and how to submit a response, whether you are managing the server yourself or using a third-party vendor.

2. Next, you will add a webhook destination in Workbench to allow your server to consume the HTTP POST requests that come from Expel. 
   • The webhook destination must be set to authenticate via one of our two available authentication methods (username and password, or HMAC header).
   • You will generate a test webhook request as part of this process, to ensure the connection is working properly.

3. Finally, you will set up a notification in Workbench to specify when Expel should send a webhook request to the webhook destination.
   • A notification must be created in order for any data to be sent to your webhook destination, because the notification tells Expel what to send and when to send it.
   • Some Expel events also allow you to specify one or more conditions for the notification.

You may set up multiple notifications to send a variety of webhook requests to a single webhook destination, or you may create multiple webhook destinations to organize your webhook requests in that way.

Webhook Data Model

The webhook body includes a payload that is always UTF-8-encoded JSON. Its structure will vary based on the Expel event you choose when you set up the notification, but it will embed a consistent series of representational Expel events that are formatted using key:value pairs. It will also include an HTML header that you will use for authentication purposes.

Some examples of Expel events include: 

• Expel Alert is created (uses the Expel Alert Event data model)
• Investigation is closed (uses the Investigation Event data model)
• Remediation Action is assigned to me (uses the Remediation Action Event data model)
• Security device has a health status change (uses the Security Device Event data model)

There are nearly 50 Expel events to choose from when setting up a webhook, and 9 different data models leveraged to create the format of the JSON body.

An example JSON body is:

{
    "rule": "investigation is created",
    "event_name": "investigation_created",
    "data": {...},
    "guid": "ab12c34d-e567-8fg9-1012-h345i67jk8lm"
}

• rule - the name of the notification that produced the webhook.
• event_name - the name of the event that triggered the notification; this name will always be associated with a specific Expel model, like an Investigation or an Expel Alert (see the Webhook Model Reference for a full breakdown of all events and models).
• data - the contents of the event as captured by Workbench plus any additional information or updates (the content here is based on the model).
• guid - the unique ID for the main object associated with the webhook.

Failure Handling

During your initial webhook setup, Expel can share error information for failed “Test Connection” requests to help determine any issues. However, Expel cannot troubleshoot any issues with webhook processing by your receiving server or endpoint, as we do not have the visibility or ability to fix these errors. We can only address internal errors.

Step 1: Prepare Your Receiving Server

You may process the webhook requests however you like, as long as the HTTP server uses one of the two available authorization methods.

Implement Recommended Best Practices

When setting up an HTTP server for consuming Expel webhooks, we recommend that you do the following to secure your webhooks:

• Make sure the server always uses HTTPS, and that it has a valid signed certificate.
• Set a limit on requests per second and on request size to help prevent Denial of Service (while it is unlikely that Expel webhooks will constitute a large volume of requests, the server should be able to handle bursts of requests).
• Configure an IP allow list if you wish to further limit unwanted traffic.
• Make sure your chosen authentication mechanism always verifies the contents of the Expel-Signature-256 header or Authorization header for every single webhook request, so that you can immediately dispose of any messages not sent by Expel.

Webhook Authentication

You will need to know where to find the authorization information within the webhook request's HTTP header.

Basic Authentication

If you choose to use basic authentication, every webhook request sent by Expel will contain the HTTP header Authorization, formatted as Basic {base64 username:password}. This header is the basic access authentication encoded username and password for validating the webhook.

Basic authorization is often used by customers who are leveraging a third-party provider for their server. Generally, the receiving system will provide a username and password for this type of authentication, and those values can be added to the username and password fields when you add a new webhook destination in Workbench.

HMAC Authentication

If you choose to use HMAC authentication, every webhook request sent by Expel will contain 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.

All webhook requests that Expel sends are encoded using UTF-8. The HMAC hex digest should be computed using the secret key and webhook payload, both encoded as UTF-8.

HTTP Response

Your server must respond to the webhook POST request with an appropriate status code (no response body is required) whenever it receives a webhook request. The codes are as follows:

• 200 - indicates the request was successfully received by the webhook, with no retries needed from Expel.
• 406 - indicates the request was rejected by the webhook, with no retries requested from Expel.
• Any other valid 4xx or 5xx code - indicates a processing failure of some kind, with retries requested; Expel uses a polynomial backoff and will resend the request at the following intervals: 1 minute, 8 minutes, 27 minutes, 64 minutes, and 125 minutes.

Step 2: Add a New Webhook Destination

You must first add a webhook destination before you can set up the notifications that will send your events and data to that destination. 

Note

You cannot edit the authentication information for a webhook after it has been created, or re-obtain the HMAC secret key. If you need to make a change to your authentication or if you have lost your secret key, you should delete the webhook and start over by adding a new one.

1. Log in to Workbench.
2. In the side menu, navigate to Settings > Organization Settings. If you have multiple organizations, you must select the appropriate organization name from the list.
3. On the My Organizations page, select the Integrations tab.
4. Scroll to the Webhooks section and select the Add a webhook destination link.
5. Complete the fields as follows:
   • Webhook destination name - enter a name that might help you identify this webhook destination.
   • Webhook destination URL - enter the destination URL, making sure to start with https://.
   • Webhook auth type - select Basic Auth to use a username and password, or HMAC Header to use HMAC authentication.
6. Do one of the following:
   • If you chose basic auth, enter the username and password.
   • If you chose HMAC, copy your secret key and save it to a secure location. You will need it for HMAC header comparison.
7. Select Add.
8. Select Test connection.
9. Look for a "Successfully sent" message to appear along with a timestamp.
   
10. Do one of the following:
    • If you are using basic auth and the test is successful, you are done. Continue to Step 3. 
    • If you are using HMAC and the test is successful, continue to the next step. 
    • If the test failed, check your URL (and HMAC signature calculations, if applicable) to be sure they are correct.

Note

If you need to update your login credentials or generate a new secret key, you must delete the webhook and start the process again. Credentials and secret keys cannot be viewed or edited after saving, and secret keys cannot be regenerated for an existing webhook.

11. For HMAC authorization only: 
    • Make sure you can successfully calculate the HMAC signature by using your secret key (this process is usually done programmatically via a script) to verify that the webhook originated from Expel.
    • Remember that the HMAC hex digest should be computed using the secret and webhook payload, both encoded as UTF-8
    • Compare this result to the Expel-Signature-256 header in the webhook request.

Step 3: Set Up the Notification

You can now set up one or more notifications that use this webhook as a destination. See About Notifications for information about the different types of Workbench notifications that are available. In this instance, you will be setting up an organization notification.

1. Still in Organization Settings, select the Notifications tab.
2. Select Add Notification.
3. Complete the fields as follows:
   • Conditions - select an event, and then select an action; some events may also allow you to add one or more conditions.
   • Notify via - select the name of the webhook destination you added in Step 2.
   • Select Save to activate the notification.

4. Repeat this process for any additional notifications you wish to set up for that webhook. 

You can also add additional webhooks at any time, and then return to your notification to add the new webhook as an additional destination in the Notify via section.