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

> Configure webhook notifications for Home Assistant or other systems with docker-icloudpd. Set notification type to webhook and define server and ID for real-time HTTP POST alerts from the container.

- Repository: [boredazfcuk/docker-icloudpd](https://github.com/boredazfcuk/docker-icloudpd)
- Tags: how-to-guide
- Published: 2026-02-26

---

**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`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/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`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/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`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/init_config.sh) script (lines 181-186) establishes default values for optional parameters, while [`launcher.sh`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/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`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/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`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/docker-compose.yml) file:

```yaml
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`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/sync-icloud.sh) (lines 1984-1992):

```bash
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:

```yaml
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`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/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`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/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`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/launcher.sh) script validates mandatory variables at startup (lines 504-511), while [`sync-icloud.sh`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/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`](https://github.com/boredazfcuk/docker-icloudpd/blob/main/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.