ComposeSync/Docs/webhooks.md

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:

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:

{
  "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:

{
  "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:

{
  "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:

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:

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:

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:

   DRY_RUN=true
   

2. Restart the service:

   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:

   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:

   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:

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.