Skip to content

Configuration

Jump to bottom
guyinwonder168 edited this page Feb 7, 2026 · 1 revision

Configuration

This guide covers all configuration options for the Redmine Webhook Plugin.

Table of Contents

Webhook Endpoints

Navigate to: Administration > Webhook Endpoints

Creating an Endpoint

  1. Click New Webhook Endpoint
  2. Fill in required fields:
Field Description Example Required
Name Descriptive identifier for the endpoint "Production Slack" Yes
URL HTTPS endpoint URL "https://hooks.slack.com/services/..." Yes
Events Events that trigger this webhook See below At least 1
Payload Mode Payload size (minimal/standard/full) "standard" Yes
Enabled Activate webhook ☑ Yes
Webhook User User to send as "service-account" Optional

Editing an Endpoint

  1. Click on endpoint name in the list
  2. Modify fields
  3. Click Save

Changes apply immediately - New events use the updated configuration.

Deleting an Endpoint

  1. Click Delete next to endpoint
  2. Confirm deletion

Impact:

  • No new webhooks will be sent to this endpoint
  • Existing delivery records are preserved
  • Can view deliveries history in "Webhook Deliveries" page

Event Types

Event Triggered When Payload Includes
Issue Created New issue added to Redmine Full issue data
Issue Updated Any field changed on existing issue Changed fields only
Issue Deleted Issue removed from Redmine Issue data (snapshot before delete)
Time Entry Created Time logged for work Full time entry data
Time Entry Updated Time entry modified Changed fields only
Time Entry Deleted Time entry removed Time entry data

Event Filtering

By default, endpoints receive all events. To filter:

  1. Edit an endpoint
  2. Under Events, select/deselect specific events
  3. Save

Use Cases:

Separate Endpoints for Different Teams:

  • Endpoint A: Only "Issue Created" → Project Management Team (Slack)
  • Endpoint B: All events → Development Team (Microsoft Teams)
  • Endpoint C: Only "Time Entry Created" → Finance Team (Custom API)

Filter by Project:

  • Create endpoint for specific project(s)
  • Use case: Client-specific webhooks
  • Note: Requires custom implementation (future feature)

Filter by User:

  • Create endpoint with specific user
  • Use case: Service account webhooks
  • Note: Requires custom implementation (future feature)

Payload Modes

Select the appropriate payload mode based on your integration needs:

Mode Size Use Case Includes
Minimal Small High volume, simple notifications Event metadata only
Standard Medium Most integrations Essential fields + changes
Full Large Full data replication All available data

Minimal Payload

{
  "event_id": "uuid",
  "event_type": "issue",
  "action": "created",
  "occurred_at": "2026-02-03T12:00:00Z",
  "resource_type": "Issue",
  "resource_id": 123,
  "actor": {
    "id": 1,
    "login": "admin",
    "name": "Administrator"
  },
  "redmine_url": "https://redmine.example.com/issues/123"
}

When to use:

  • Simple notification systems
  • When bandwidth is limited
  • When you don't need issue details
  • Testing webhook connectivity

Standard Payload

{
  "event_id": "uuid",
  "event_type": "issue",
  "action": "updated",
  "occurred_at": "2026-02-03T12:00:00Z",
  "resource_type": "Issue",
  "resource_id": 123,
  "actor": { "id": 1, "login": "admin", "name": "Administrator" },
  "redmine_url": "https://redmine.example.com/issues/123",
  "issue": {
    "id": 123,
    "subject": "Bug fix needed",
    "description": "Fix authentication...",
    "status": { "id": 2, "name": "In Progress" },
    "priority": { "id": 4, "name": "High" },
    "tracker": { "id": 1, "name": "Bug" },
    "assigned_to": { "id": 2, "login": "developer", "name": "Developer" },
    "project": { "id": 5, "name": "Main Project" },
    "author": { "id": 1, "login": "admin", "name": "Administrator" },
    "last_note": "Looking into this",
    "custom_fields": [
      { "id": 1, "name": "Severity", "value": "Critical" }
    ]
  },
  "changes": {
    "status": { "old": "New", "new": "In Progress" },
    "assigned_to": { "old": null, "new": { "id": 2, "login": "developer" } }
  }
}

When to use:

  • Most webhook integrations (Slack, Teams)
  • When you need issue context
  • Balancing detail vs. size

Full Payload

Same as Standard payload but includes additional fields like:

  • Full journal history
  • All attachments metadata
  • Complete relations
  • Watchers list

When to use:

  • Custom integrations requiring full data
  • Data synchronization systems
  • When bandwidth is not a concern

Authentication

Webhook User

Webhooks can be sent as a specific user (useful for audit trails):

  1. Create or edit an endpoint
  2. Set Webhook User to a Redmine user
  3. Save

Benefits:

  • All webhook requests show as that user in Redmine logs
  • Clear audit trail in Redmine
  • Separate from actual modifier

API Key in URL

Add authentication by including API key in webhook URL:

https://hooks.example.com/webhook?api_key=YOUR_SECRET_KEY

Pros:

  • Simple to implement
  • Easy to rotate keys

Cons:

  • Key exposed in logs
  • URL may be cached

HMAC Signature (Recommended)

For secure authentication, use HMAC-SHA256 signatures:

Setup (Plugin Side - Future Feature):

  1. Generate secret key: openssl rand -hex 32
  2. Add to Redmine settings (custom field)
  3. Plugin signs payload with HMAC-SHA256

External Verification:

import hmac
import json

secret = "your_secret_key_here"
payload = json.loads(request_body)

# Calculate expected signature
expected_sig = hmac.new(
  payload_bytes,
  secret.encode('utf-8'),
  hashlib.sha256
).hexdigest()

# Get signature from payload
received_sig = payload.get('signature')

if received_sig == expected_sig:
  print("Signature verified!")
  # Process webhook
else:
  print("Invalid signature!")
  # Reject webhook

OAuth 2.0 Bearer Token

curl -X POST https://hooks.example.com/webhook \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d @payload.json

Global Settings

Navigate to: Administration > Plugins > Redmine Webhook Plugin (Configure)

Global Pause

Pause all webhook deliveries:

  1. Navigate to: Administration > Plugins
  2. Find: Redmine Webhook Plugin
  3. Click: Configure
  4. Set Pause webhook deliveries to Yes
  5. Save

Effect:

  • ❌ No new deliveries will be created
  • ❌ No pending deliveries will be sent
  • ✅ Existing delivery records remain visible
  • ✅ Can still view and export delivery logs

Use Cases:

  • Emergency maintenance windows
  • External service downtime
  • Investigation period
  • Testing new integrations

Retention Settings

Configure automatic cleanup of old deliveries:

  1. Navigate to plugin configuration
  2. Set Retention Period (default: 30 days)
  3. Save

Effect:

  • ✅ Automatic cleanup via cron job
  • ✅ Applies to successful and failed deliveries
  • ✅ Preserves recent delivery history
  • ✅ Reduces database size

Advanced Configuration

Batch Processing

Control number of deliveries processed per rake task:

# Process 100 deliveries per batch
RAILS_ENV=production BATCH_SIZE=100 bundle exec rake redmine:webhooks:process

# Process default (50)
RAILS_ENV=production bundle exec rake redmine:webhooks:process

Cron Job Setup:

# Edit crontab
crontab -e

# Run every 5 minutes
*/5 * * * * cd /var/www/redmine && RAILS_ENV=production bundle exec rake redmine:webhooks:process

Custom Retry Policy

Modify retry behavior (future feature - requires code changes):

# Example configuration
RedmineWebhookPlugin::Webhook::RetryPolicy.configure(
  max_attempts: 10,        # Default: 5
  base_delay: 60,        # Default: 1 minute
  backoff_multiplier: 3  # Default: 2
)

Debug Mode

Enable detailed logging:

  1. Edit config/additional_environment.rb:

    config.log_level = :debug

  2. Restart Redmine

  3. Check logs:

    tail -f /var/log/redmine/production.log | grep webhook

Debug Output Includes:

  • Payload content being sent
  • HTTP request/response details
  • Retry attempts
  • Error stack traces

Configuration Examples

Example 1: Slack Integration

# Create Slack webhook endpoint
URL: https://hooks.slack.com/services/T00000000/B00000000/XXXXXXX
Events: Issue Created, Issue Updated
Payload Mode: Standard
Webhook User: service-account

Example 2: Microsoft Teams Integration

# Create Teams webhook endpoint
URL: https://outlook.office.com/webhook/XXXXXX-XXXX-XXXX-XXXXXX/IncomingWebhook/...
Events: All events
Payload Mode: Full
Webhook User: notification-bot

Example 3: Custom API Integration

# Create custom API endpoint
URL: https://api.example.com/v1/webhooks/redmine
Events: Issue Created, Time Entry Created
Payload Mode: Standard
Authentication: API Key in URL

Example 4: Development Environment

# Use minimal payload for faster testing
Payload Mode: Minimal
Events: Only what's needed for testing
No authentication (internal network)

Need Help? See Home or Troubleshooting

Clone this wiki locally