How to Configure Webhook Notifications for Home Assistant or Other Systems with docker-icloudpd

Set NOTIFICATION_TYPE=webhook and define WEBHOOK_SERVER, WEBHOOK_ID, and optional variables like WEBHOOK_PORT and WEBHOOK_HTTPS to enable real-time HTTP POST notifications from the boredazfcuk/docker-icloudpd container to Home Assistant or any webhook-compatible service.

The boredazfcuk/docker-icloudpd container provides a flexible notification subsystem that alerts you when iCloud downloads complete, authentication cookies expire, or sync errors occur. By configuring webhook notifications, you can integrate these events directly into Home Assistant automation workflows or generic HTTP endpoints without relying on third-party notification services.

Understanding the Webhook Notification Architecture

The notification logic resides in sync-icloud.sh, which constructs and dispatches HTTP POST requests when specific events trigger. When NOTIFICATION_TYPE is set to webhook (or openhab for OpenHAB-specific formatting), the script assembles the target URL from discrete environment variables and transmits a JSON payload containing the event title and message.

According to the source code in sync-icloud.sh (lines 352-360), the script determines the URL scheme (http or https) based on the WEBHOOK_HTTPS variable, then concatenates the server, port, path, and ID components (lines 354-362) before sending the payload via curl (lines 1984-1992).

Required Environment Variables for Webhook Configuration

Configuration occurs entirely through environment variables defined in your Docker Compose file or .env file. The init_config.sh script (lines 181-186) establishes default values for optional parameters, while launcher.sh (lines 504-511) validates that mandatory variables are present before the container starts.

Mandatory variables:

• NOTIFICATION_TYPE: Set to webhook to enable webhook notifications.
• WEBHOOK_SERVER: Hostname or IP address of the receiving server.
• WEBHOOK_ID: The unique identifier or secret token the webhook endpoint expects.

Optional variables with defaults (documented in CONFIGURATION.md lines 135-169):

• WEBHOOK_PORT: TCP port (default: 8123).
• WEBHOOK_PATH: URL path, must start and end with / (default: /api/webhook/).
• WEBHOOK_HTTPS: Use HTTPS when true, HTTP when false (default: false).
• WEBHOOK_BODY: JSON key containing the payload (default: data).
• WEBHOOK_INSECURE: Skip TLS certificate verification when true (default: unset/false).

Configuring Webhook Notifications for Home Assistant

Home Assistant exposes webhook endpoints through the Webhook integration, typically accessible at /api/webhook/WEBHOOK_ID. The default configuration values in docker-icloudpd align with Home Assistant's defaults, requiring minimal customization.

Docker Compose Configuration

Define the environment variables in your docker-compose.yml file:

services:
  icloudpd:
    image: ghcr.io/boredazfcuk/docker-icloudpd:latest
    container_name: icloudpd
    environment:
      - NOTIFICATION_TYPE=webhook
      - WEBHOOK_SERVER=homeassistant.local
      - WEBHOOK_PORT=8123
      - WEBHOOK_PATH=/api/webhook/
      - WEBHOOK_ID=your_long_webhook_id_here
      - WEBHOOK_HTTPS=true
      - WEBHOOK_BODY=data
      - WEBHOOK_INSECURE=false
    volumes:
      - ./photos:/data

Testing the Webhook Manually

Before relying on automated notifications, verify connectivity using curl to simulate the payload format used by sync-icloud.sh (lines 1984-1992):

title="iCloudPD Test"
message="Backup completed successfully"
payload=$(printf '{"data":"%s - %s"}' "$title" "$message")

curl -X POST "https://homeassistant.local:8123/api/webhook/YOUR_WEBHOOK_ID" \
     -H "Content-Type: application/json" \
     -d "$payload"

Alternative Webhook Configurations

While Home Assistant is a common target, the webhook implementation supports any HTTP endpoint that accepts POST requests with JSON payloads.

OpenHAB Integration

For OpenHAB users, set NOTIFICATION_TYPE=openhab (which uses the same underlying webhook logic but formats the payload appropriately) or use the standard webhook type with custom paths:

environment:
  - NOTIFICATION_TYPE=webhook
  - WEBHOOK_SERVER=openhab.local
  - WEBHOOK_PORT=8080
  - WEBHOOK_PATH=/rest/items/PhoneBackup/
  - WEBHOOK_ID=state
  - WEBHOOK_HTTPS=false

Generic HTTP Endpoints

For custom APIs, adjust WEBHOOK_PATH and WEBHOOK_BODY to match your endpoint's expected schema. The WEBHOOK_BODY variable defines the JSON key that wraps the notification message (default: data).

Validation and Troubleshooting

The container performs rigorous validation to prevent silent failures. The launcher.sh script (lines 504-511) checks that mandatory variables are defined before the sync process begins, emitting clear error messages if configuration is incomplete.

Common issues and solutions:

• Connection refused: Verify WEBHOOK_SERVER and WEBHOOK_PORT match your receiving service. Home Assistant typically runs on port 8123, while other services may use 80, 443, or custom ports.
• TLS certificate errors: If using self-signed certificates, set WEBHOOK_INSECURE=true to bypass verification (not recommended for production). For production deployments, ensure proper certificates are in place.
• 404 Not Found: Confirm WEBHOOK_PATH starts and ends with / as required by the validation logic in sync-icloud.sh (lines 354-362).

Summary

Configuring webhook notifications in docker-icloudpd enables real-time integration with Home Assistant and other automation platforms:

• Set NOTIFICATION_TYPE=webhook to enable the notification subsystem.
• Define WEBHOOK_SERVER, WEBHOOK_ID, and optionally WEBHOOK_PORT, WEBHOOK_PATH, and WEBHOOK_HTTPS to target your specific endpoint.
• The launcher.sh script validates mandatory variables at startup (lines 504-511), while sync-icloud.sh handles the actual HTTP POST transmission (lines 1984-1992).
• Test configurations manually using curl before deploying to ensure connectivity and payload format compatibility.

Frequently Asked Questions

What is the default webhook port for Home Assistant?

Home Assistant uses port 8123 by default, which matches the WEBHOOK_PORT default value in docker-icloudpd. If your Home Assistant instance runs on a different port, explicitly set WEBHOOK_PORT to match your configuration.

Can I use webhook notifications without HTTPS?

Yes, by setting WEBHOOK_HTTPS=false (the default), the container sends HTTP requests instead of HTTPS. This is suitable for local networks or reverse proxy setups, though HTTPS is recommended for remote endpoints to ensure encrypted communication.

How do I find my Home Assistant webhook ID?

Create a webhook automation in Home Assistant through Settings > Automations & Scenes > Create Automation > Webhook. Home Assistant generates a unique random ID (for example, abc123def456). Copy this ID into the WEBHOOK_ID environment variable. Alternatively, manually define a webhook ID in your automation configuration if you prefer a specific value.

Why does my container fail to start with a webhook configuration error?

The launcher.sh script validates that WEBHOOK_SERVER and WEBHOOK_ID are defined before starting the sync process (lines 504-511). If either variable is missing, the container aborts with a clear error message. Ensure both variables are set in your environment file or Docker Compose configuration.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}