Automating device workflows with Esper webhooks

Esper webhooks let you trigger actions in your own systems the moment something happens on a device — a Blueprint convergence completes, a device goes offline, or a compliance state changes. This guide walks through setting up a webhook and handling the payload.

What you can listen for

Esper fires webhook events for a range of device lifecycle moments. Some of the most useful:

Step 1: Create a webhook endpoint

Your endpoint needs to:

• Accept POST requests
• Return 200 OK within 5 seconds (Esper will retry on timeout)
• Be accessible over HTTPS

A minimal Python (Flask) receiver:

from flask import Flask, request, jsonify
import hmac, hashlib

app = Flask(__name__)
WEBHOOK_SECRET = os.environ["ESPER_WEBHOOK_SECRET"]

@app.route("/esper/webhook", methods=["POST"])
def handle_event():
    # Verify the signature (recommended)
    sig = request.headers.get("X-Esper-Signature", "")
    body = request.get_data()
    expected = hmac.new(
        WEBHOOK_SECRET.encode(), body, hashlib.sha256
    ).hexdigest()
    if not hmac.compare_digest(sig, expected):
        return jsonify({"error": "invalid signature"}), 401

    event = request.json
    event_type = event.get("type")

    if event_type == "device.compliance_change":
        device = event["data"]["device_name"]
        state  = event["data"]["compliance_state"]
        print(f"{device} compliance changed to: {state}")
        # Trigger your alerting, ticketing, or logging logic here

    return jsonify({"received": True}), 200

Step 2: Register the webhook in Esper

1. In the Esper console, go to Settings → Webhooks → Add Webhook.
2. Enter your endpoint URL.
3. Select the event types you want to receive.
4. Copy the webhook secret — you'll use this to verify incoming payloads.
5. Save and use the Send Test Event button to confirm your endpoint is receiving correctly.

Step 3: Handle the payload

Every webhook payload follows this structure:

{
  "type": "device.compliance_change",
  "timestamp": "2026-08-25T10:30:00Z",
  "enterprise_id": "YOUR_ENTERPRISE_ID",
  "data": {
    "device_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "device_name": "KIOSK-042",
    "compliance_state": "drift",
    "blueprint_id": "bp-xxxxxxxx"
  }
}

Common patterns

• Slack alert when a device goes offline: Listen for device.status_change, filter for status: offline, post to a Slack channel via the Slack API.
• Auto-create a support ticket on compliance drift: Listen for device.compliance_change, filter for compliance_state: drift, create a ticket in your helpdesk with the device details pre-filled.
• Log deployment results to a database: Listen for blueprint.converge_complete, write the result (device, Blueprint, success/failure, timestamp) to your data warehouse for compliance reporting.

Full webhook documentation: api.esper.io

Note: Always verify the webhook signature before processing the payload. Never expose your webhook secret in client-side code or commit it to a repository.