ESPHome Webhook Service

A Docker-based webhook service for automating ESPHome device compilation and deployment with file watching capabilities.

Features

• Webhook Endpoints: Trigger ESPHome operations via HTTP POST requests
• File Watching: Automatically detect YAML changes and trigger compilation/upload
• REST API: List devices, check health, and manage operations
• Docker Compose: Easy deployment with ESPHome dashboard
• Debouncing: Prevent duplicate operations from rapid file changes
• Thread-Safe: Concurrent operation handling with locks

Quick Start

1. Start the Services

cd esphome-webhook-service
docker-compose up -d

This starts two services:

• ESPHome Dashboard: http://localhost:6052 (host network mode)
• Webhook Service: http://localhost:5000

2. Access the Services

• ESPHome Dashboard: http://localhost:6052
• Webhook API: http://localhost:5000/health

3. Stop the Services

docker-compose down

Environment Variables

Configure the webhook service behavior in docker-compose.yml:

Variable	Default	Description
ESPHOME_CONFIG_DIR	/config	Directory containing device configs
AUTO_COMPILE	true	Auto-compile on YAML file changes
AUTO_UPLOAD	false	Auto-upload on YAML file changes (⚠️ use with caution)
DEBOUNCE_SECONDS	5	Delay before triggering operations after file change

API Endpoints

Health Check

curl http://localhost:5000/health

List Devices

curl http://localhost:5000/devices

Validate Configuration

curl -X POST http://localhost:5000/webhook/validate/ades-office-control-panel

Compile Device

curl -X POST http://localhost:5000/webhook/compile/ades-office-control-panel

Upload Device (OTA)

curl -X POST http://localhost:5000/webhook/upload/ades-office-control-panel

Compile and Upload

curl -X POST http://localhost:5000/webhook/run/ades-office-control-panel

File Watching

The service automatically watches all YAML files in the config directory. When a main.yaml file is modified:

1. Auto-Compile Enabled: Automatically compiles the device configuration
2. Auto-Upload Enabled: Automatically uploads firmware to the device (OTA)

⚠️ WARNING: Only enable AUTO_UPLOAD=true if you're confident in your changes and have physical access to devices in case of failures.

Integration Examples

GitHub Actions Webhook

Trigger compilation after pushing changes:

name: ESPHome Compile

on:
  push:
    paths:
      - '**/*.yaml'

jobs:
  compile:
    runs-on: ubuntu-latest
    steps:
      - name: Trigger Webhook
        run: |
          curl -X POST http://your-server:5000/webhook/compile/ades-office-control-panel

Home Assistant Automation

Create an automation to compile devices:

automation:
  - alias: "Compile ESPHome Device"
    trigger:
      platform: webhook
      webhook_id: esphome_compile
    action:
      service: rest_command.compile_device
      data:
        device: "{{ trigger.data.device }}"

rest_command:
  compile_device:
    url: "http://localhost:5000/webhook/compile/{{ device }}"
    method: POST

Directory Structure

esphome-webhook-service/
├── app.py                  # Webhook service with file watching
├── Dockerfile              # Container image definition
├── requirements.txt        # Python dependencies
├── docker-compose.yml      # Service orchestration
├── README.md              # This file
└── config/                 # Device configurations (mounted as /config)
    ├── ades-office-control-panel/
    │   └── main.yaml
    ├── Old_Phone_Doorbell/
    │   └── main.yaml
    └── Oekoboiler/
        └── main.yaml

Troubleshooting

Service Won't Start

Check logs:

docker-compose logs webhook
docker-compose logs esphome

Webhook Returns 404

Ensure the device name matches the directory name:

curl http://localhost:5000/devices

OTA Upload Fails

1. Verify device is on the same network
2. Check ESPHome logs: docker-compose logs esphome
3. Ensure OTA password is correct in secrets.yaml
4. Try using host network mode for webhook service (uncomment in docker-compose.yml)

File Watcher Not Triggering

1. Check that AUTO_COMPILE is set to true
2. Verify the file path is correct
3. Check webhook logs for file change events
4. Ensure Docker has permission to watch the mounted volume

Development

Run Locally (Without Docker)

# Install dependencies
pip install -r requirements.txt
pip install esphome

# Set environment variables
export ESPHOME_CONFIG_DIR=/path/to/esphome2/config
export AUTO_COMPILE=true
export AUTO_UPLOAD=false

# Run the service
python app.py

Build Custom Image

docker build -t esphome-webhook:custom .

Security Considerations

• The webhook service has no authentication by default
• Only expose port 5000 on trusted networks
• Use a reverse proxy (nginx, Traefik) with authentication for external access
• Keep AUTO_UPLOAD=false unless absolutely necessary
• Review changes before enabling auto-upload

License

Same as parent repository (see LICENSE file).