Managing webhook requests

To allow the integration of Expel data without API polling, Expel can send webhook requests to external servers.

Webhook data model

The webhook body is UTF-8-encoded JSON.

The webhook json itself is a wrapper around a "change event", which is a structure that provides all the contextual data around an event within Workbench. This object varies by event but embeds a consistent series of representational Expel objects, for example, Investigation and RemediationAction.

{
	"guid": "1a9c6d7a-78e6-4238-8cd7-8d2ec2492cab",
	"rule": "incident is created",
	"event_name": "incident_created",
	"data": {...}
}

Webhook signature

Every webhook sent by Expel contains the HTTP header Expel-Signature-256, formatted as sha256={some hash}. The header is a SHA-256 HMAC of the webhook payload bytes, generated using a secret key. The secret key is provided through Workbench when the webhook integration is created. See Adding a webhook integration.

Example Python snippet showing signature header verification

import hmac
import hashlib

# secret_bytes, accessible by this verification secret

# request object sent by Expel has been processed, with the body_bytes and header extracted
# body_bytes
# signature_header

# extract the signature
header_split = siganture_header.split("=")
if len(header_split) < 2:
	# not a valid signature header
	return

expel_sig = header_split[1]

# generate an hmac of the body_bytes
local_sig = hmac.new(secret_bytes, body_bytes, digestmod=hashlib.sha256).hexdigest()

# constant time compare, returns a boolean
valid_webhook = hmac.compare_digest(expel_sig, local_sig)

Webhook POST behavior

The receiving server is expected to reply with a status code to the webhook request. No response body is required.

Adding a webhook integration

To subscribe to webhook notifications in Workbench, you need to add at least one webhook integration.

Adding 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.

Best practices for securing webhooks

When setting up an HTTP server for consuming Expel webhooks, use the following best practices: