# Webhook Notifications

This guide covers how to set up and configure webhook notifications in ComposeSync.

## Overview

ComposeSync can send webhook notifications when updates are applied or when errors occur. This is useful for:
- Monitoring update status remotely
- Integrating with notification systems (Discord, Slack, etc.)
- Alerting on failed updates
- Keeping track of when stacks are updated

## Configuration

To enable webhook notifications, add this to your `.env` file:

```env
NOTIFICATION_WEBHOOK_URL=https://your-webhook-url.com/endpoint
```

## Webhook Payload

The webhook will be called with a JSON payload containing:

- `event`: The type of event (`update_success`, `update_failure`, `error`)
- `stack_name`: The name of the stack being updated
- `timestamp`: When the event occurred
- `message`: A human-readable description of what happened
- `version_id`: The version identifier for the update (if applicable)
- `diff`: A unified diff (truncated to 50 lines) showing the changes applied to the main compose file (for update_success and update_failure events; null for errors)

## Event Types

### Update Success

Sent when a stack is successfully updated. Includes a diff of the changes:

```json
{
  "event": "update_success",
  "stack_name": "immich",
  "timestamp": "2024-01-15T10:30:00Z",
  "message": "Successfully updated stack immich to version a1b2c3d",
  "version_id": "a1b2c3d",
  "diff": "--- compose-a1b2c3d.yml.bak\n+++ docker-compose.yml\n@@ -1,6 +1,6 @@\n version: '3.8'\n services:\n   immich-server:\n-    image: ghcr.io/immich-app/immich-server:release\n+    image: ghcr.io/immich-app/immich-server:release-1.91.0\n... (diff truncated, showing first 50 lines)"
}
```

### Update Failure

Sent when a stack update fails and rollback occurs. Includes the diff that was attempted:

```json
{
  "event": "update_failure",
  "stack_name": "immich",
  "timestamp": "2024-01-15T10:30:00Z",
  "message": "Failed to update stack immich, rolled back to previous version",
  "version_id": "a1b2c3d",
  "diff": "--- compose-a1b2c3d.yml.bak\n+++ docker-compose.yml\n@@ -1,6 +1,6 @@\n ... (diff truncated, showing first 50 lines)"
}
```

### Error

Sent when a general error occurs. The diff field is null:

```json
{
  "event": "error",
  "stack_name": "immich",
  "timestamp": "2024-01-15T10:30:00Z",
  "message": "Failed to download compose file for stack immich",
  "version_id": null,
  "diff": null
}
```

## Integration Examples

### Discord

1. Create a Discord webhook in your server settings
2. Configure ComposeSync with the webhook URL:

```env
NOTIFICATION_WEBHOOK_URL=https://discord.com/api/webhooks/YOUR_WEBHOOK_ID/YOUR_WEBHOOK_TOKEN
```

Discord will automatically format the JSON payload into a readable message.

### Slack

1. Create a Slack webhook in your workspace settings
2. Configure ComposeSync with the webhook URL:

```env
NOTIFICATION_WEBHOOK_URL=https://hooks.slack.com/services/YOUR_WEBHOOK_URL
```

Slack will display the notification in your configured channel.

### Custom Webhook Server

You can create your own webhook server to handle notifications:

```python
from flask import Flask, request
import json

app = Flask(__name__)

@app.route('/webhook', methods=['POST'])
def webhook():
    data = request.json
    
    if data['event'] == 'update_success':
        print(f"✅ {data['stack_name']} updated successfully")
    elif data['event'] == 'update_failure':
        print(f"❌ {data['stack_name']} update failed")
    elif data['event'] == 'error':
        print(f"⚠️ Error with {data['stack_name']}: {data['message']}")
    
    return 'OK', 200

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=5000)
```

## Dry-Run Mode

**Important:** Webhook notifications are sent regardless of whether you're in dry-run mode. This allows you to test your webhook configuration safely without applying actual changes.

## Testing Webhooks

To test your webhook configuration:

1. Enable dry-run mode:
   ```env
   DRY_RUN=true
   ```

2. Restart the service:
   ```bash
   sudo systemctl restart composesync
   ```

3. Check your webhook endpoint for test notifications

## Troubleshooting

### Webhook Not Sent

If webhooks aren't being sent:

1. Check the webhook URL is correct
2. Verify the service can reach the webhook endpoint
3. Check the service logs for webhook errors:
   ```bash
   sudo journalctl -u composesync -f
   ```

### Webhook Failures

If webhook calls are failing:

1. Check the webhook endpoint is accessible
2. Verify the endpoint accepts POST requests
3. Check for authentication requirements
4. Test the webhook URL manually:
   ```bash
   curl -X POST -H "Content-Type: application/json" \
     -d '{"test": "message"}' \
     https://your-webhook-url.com/endpoint
   ```

### Rate Limiting

Some webhook services have rate limits. If you're hitting limits:

1. Increase the update interval
2. Use a different webhook service
3. Implement your own webhook server with rate limiting

## Best Practices

### 1. Use HTTPS

Always use HTTPS URLs for webhooks to ensure security:
```env
NOTIFICATION_WEBHOOK_URL=https://your-webhook-url.com/endpoint
```

### 2. Test Your Webhook

Always test your webhook configuration with dry-run mode before going live.

### 3. Monitor Webhook Failures

Set up monitoring for webhook failures to ensure you don't miss important notifications.

### 4. Use Descriptive Messages

The webhook messages are designed to be human-readable and informative.

### 5. Handle Different Event Types

Configure your webhook endpoint to handle all event types appropriately.

## Advanced Configuration

### Custom Webhook Headers

If your webhook service requires custom headers, you may need to modify the webhook sending code in the update script.

### Multiple Webhooks

To send to multiple webhook endpoints, you can modify the webhook sending function to iterate through multiple URLs.

### Webhook Authentication

For webhooks requiring authentication, you can include credentials in the URL or modify the webhook sending code to include headers.