Skip to content

Usage Guide

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

Usage Guide

This guide covers monitoring, replaying, and managing webhook deliveries.

Table of Contents

Monitoring Deliveries

Navigate to: Administration > Webhook Deliveries

Understanding Delivery Status

Status Color Meaning Retry?
Pending Blue Queued, waiting to be sent
Success Green Delivered successfully No
Failed Orange HTTP error, will retry Yes
Dead Red All retries exhausted No

Viewing Delivery List

The main deliveries page shows all webhook attempts:

Columns:

  1. Endpoint - Which webhook endpoint
  2. Event - Event type + action (e.g., "issue created")
  3. Resource - Issue ID or Time Entry ID
  4. Status - Pending, Success, Failed, Dead
  5. Scheduled At - When queued for delivery
  6. Attempt Count - Number of retry attempts
  7. Last Attempt - Timestamp of last HTTP request
  8. Actions - Replay, Delete, Purge options

Filtering Deliveries

Use filters at the top of the page to find specific deliveries:

Filter Options:

  • By Endpoint - Select specific webhook endpoint from dropdown
  • By Status - Filter by: Pending, Success, Failed, Dead
  • By Date Range - Set start and end dates
  • By Resource ID - Search for specific issue or time entry

Use Cases:

  • Debug why a webhook failed → Filter: Failed → Click delivery
  • Audit all webhooks for an issue → Filter: Resource ID
  • Check recent activity → Filter: Date Range → Today → Success

Viewing Delivery Details

Click on any delivery row to see complete information:

Request Information:

  • Request Headers - HTTP headers sent
  • Request Body - Full payload sent
  • Timestamp - When request was sent

Response Information:

  • Response Status Code - HTTP status (200, 404, 500, etc.)
  • Response Body - Response from external endpoint
  • Error Message - Detailed error (if failed)

Delivery Metadata:

  • Event ID - Unique event identifier
  • Occured At - When event happened in Redmine
  • Actor - Redmine user who triggered event
  • Redmine URL - Link to Redmine issue/time entry

Replaying Failed Deliveries

Single Replay

Retry a single failed or dead delivery:

  1. Click on a Failed or Dead delivery row
  2. Click Replay button in the delivery details
  3. Confirm in modal
  4. New delivery created with same payload

What Happens:

  • ✅ New delivery record created in "Pending" status
  • ✅ HTTP request sent immediately
  • ❌ Original delivery remains in history (not modified)
  • ✅ New delivery visible in deliveries list

Use Cases:

  • External service recovered from outage
  • Temporary network issue resolved
  • Authentication fixed

Bulk Replay

Replay multiple failed or dead deliveries:

  1. Apply filters to show only failed/dead deliveries
    • Filter: Status = Failed or Dead
    • Optionally filter by: Endpoint or date range
  2. Check boxes for deliveries to replay
  3. Click Replay Selected button (top right)
  4. Confirm in modal

What Happens:

  • ✅ New delivery records created for each selected delivery
  • ✅ All queued immediately
  • ✅ Original records preserved

Use Cases:

  • After external service recovery (bulk replay)
  • After testing new authentication credentials
  • After fixing webhook endpoint URL

Exporting to CSV

Export delivery logs for analysis or external processing.

Export Steps

  1. Apply your desired filters
    • By endpoint
    • By status
    • By date range
  2. Click Export to CSV button (top right)
  3. Download the generated file

CSV Format

Endpoint,Event,Resource ID,Status,Scheduled At,Attempt Count,Last Attempt,Error Message,Updated At
Production Slack,issue created,123,Success,2026-02-03 12:00:00,1,2026-02-03 12:00:00,,
Development Slack,issue updated,456,Failed,2026-02-04 09:00:00,3,2026-02-04 09:00:01,404 Not Found,2026-02-04 09:00:05,

Field Descriptions:

  • Endpoint - Name of webhook endpoint
  • Event - Event type and action
  • Resource ID - Issue ID or Time Entry ID
  • Status - Final delivery status
  • Scheduled At - When delivery was queued
  • Attempt Count - Number of HTTP attempts
  • Last Attempt - Timestamp of last HTTP request
  • Error Message - Error details (if applicable)
  • Updated At - When delivery was last updated

Use Cases

For Analysis:

  • Calculate webhook success rates
  • Identify failing endpoints
  • Analyze error patterns
  • Track delivery performance

For External Processing:

  • Import into analytics tools (Splunk, ELK)
  • Generate reports
  • Data warehousing

For Auditing:

  • Compliance verification
  • Security audit trails
  • Change tracking

Bulk Operations

Bulk Actions Available

From the Webhook Deliveries page, you can perform:

  1. Replay Selected - Retry failed/dead deliveries
  2. Export Selected - Download filtered records as CSV
  3. Purge Selected - Delete old delivery records

Performing Bulk Actions

  1. Apply filters to select records
  2. Select records using checkboxes (leftmost column)
  3. Click desired action button (top right)
  4. Confirm in modal

Purging Old Records

Clean up delivery database to maintain performance.

Manual Purge

  1. Filter to old deliveries (e.g., older than 30 days)
  2. Check boxes for records to purge
  3. Click Purge button
  4. Confirm deletion

What Gets Deleted:

  • ✅ Delivery records permanently removed
  • ✅ Database size reduced
  • ✅ Performance improved

Note: Purged records cannot be recovered.

Automatic Purge

Configure automatic cleanup via plugin settings:

  1. Navigate to: Administration > Plugins > Redmine Webhook Plugin (Configure)
  2. Set Retention Period (in days)
  3. Save

How It Works:

  • A cron job runs periodically
  • Automatically deletes deliveries older than retention period
  • Applies to both successful and failed deliveries

Delivery Status Reference

Pending

Definition: Delivery queued, waiting to be sent

Common Causes:

  • New delivery created
  • Global pause was active (now disabled)
  • Previous batch processing not complete

Action Needed: None (will be processed automatically)

Success

Definition: HTTP request returned 200-299

Indicates:

  • ✅ Webhook endpoint received the payload
  • ✅ Integration working correctly

Response Codes:

  • 200 - OK
  • 201 - Created
  • 202 - Accepted
  • 204 - No Content (acknowledged)

Failed

Definition: HTTP request returned 4xx or 5xx error

Common Error Codes:

  • 400 - Bad Request (invalid payload)
  • 401 - Unauthorized (authentication failed)
  • 404 - Not Found (invalid endpoint URL)
  • 429 - Too Many Requests (rate limiting)
  • 500 - Internal Server Error
  • 502 - Bad Gateway
  • 503 - Service Unavailable
  • 504 - Gateway Timeout

Action Needed: Plugin will retry automatically

Dead

Definition: All retry attempts exhausted (max: 5)

Common Causes:

  • Endpoint permanently offline
  • Invalid authentication (not recoverable)
  • DNS resolution failed
  • SSL certificate error

Action Needed:

  • Fix endpoint configuration
  • Replay delivery manually
  • Update webhook URL if changed

Performance Tips

Optimize Delivery Monitoring

  1. Use Filters Wisely

    • Filter by date range instead of loading all records
    • Focus on failed/dead deliveries for troubleshooting

  2. Export Regularly

    • Export for external analysis
    • Delete old exports to save space

  3. Schedule Purges

    • Set appropriate retention period (30-90 days)
    • Automatic cleanup maintains database performance

  4. Monitor Endpoint Health

    • Check external service status
    • Review failed delivery patterns
    • Update endpoint configurations

Best Practices

For High-Volume Redmine Instances:

  • Use Minimal payload mode when possible
  • Increase BATCH_SIZE for rake task processing
  • Implement rate limiting on external services
  • Monitor delivery queue growth

For Security-Sensitive Environments:

  • Enable HMAC signature authentication
  • Use HTTPS for all webhook endpoints
  • Implement IP whitelisting on external services
  • Set appropriate retention periods

Need Help? See Home or Configuration

Clone this wiki locally