222 lines
No EOL
5.9 KiB
Markdown
222 lines
No EOL
5.9 KiB
Markdown
# 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. |