Skip to main content

Managing Issues

This guide shows you how to identify, investigate, and resolve webhook delivery problems using Hooklistener's automated Issue tracking. You'll learn how to work with Issues efficiently and prevent recurring problems.

What You'll Learn​

  • How to find and prioritize Issues
  • How to investigate Issue root causes
  • How to resolve Issues effectively
  • How to prevent Issues from recurring
  • Common Issue patterns and solutions

Prerequisites​

  • A Hooklistener account with active Bridges
  • Understanding of Issues concept
  • Basic familiarity with Events and Destinations

Understanding Issues​

Issues are automatically created when webhook deliveries fail. Hooklistener groups similar failures together, making it easy to identify and fix problems.

When Issues Are Created​

Issues are created for:

  • Network errors (timeouts, connection refused)
  • HTTP errors (4xx, 5xx status codes)
  • Authentication failures
  • Circuit breaker activations
  • Transformation errors

How Issues Are Grouped​

Similar failures are grouped into a single Issue by:

  • Destination
  • Error type
  • Error message
  • Bridge

This prevents being overwhelmed by individual failures.

Finding Issues​

Issues Dashboard​

Access Issues from the main navigation:

Navigate to: Issues

Filter by status:

  • Open: New Issues requiring attention
  • Work in Progress: Issues being investigated
  • Closed: Resolved Issues

Sort by:

  • Last occurrence (default - most recent first)
  • Occurrence count (highest first)
  • Creation date

Issue Priority​

Prioritize Issues by:

Occurrence count: High count = affects many webhooks

  • 100+ occurrences: Critical
  • 10-100: High priority
  • 1-10: Medium priority

Recency: Recent occurrences = ongoing problem

  • Last hour: Investigate immediately
  • Last day: High priority
  • Older: Lower priority

Destination: Critical destinations = higher priority

  • Production systems: Critical
  • Customer-facing: High
  • Internal tools: Medium

Investigating Issues​

Step 1: Review Issue Details​

Click on an Issue to see:

Summary:

  • Title and status
  • Occurrence count
  • First and last occurrence times
  • Bridge and Destination info

Error details:

  • Error type (network, HTTP, auth, etc.)
  • Error message
  • HTTP status code (if applicable)

Affected webhooks:

  • List of failed deliveries
  • Full request/response details

Step 2: Examine Recent Failures​

Look at the most recent failures:

  1. Click "View Affected Webhooks"
  2. Select the most recent failure
  3. Check:
    • Request sent to destination
    • Response received (or error)
    • Status code and error message
    • Headers and authentication

Step 3: Identify the Pattern​

Common patterns:

All failures:

  • Destination is completely down
  • Configuration error
  • Authentication problem

Intermittent failures:

  • Destination is unstable
  • Rate limiting
  • Network issues

Specific webhooks only:

  • Certain webhook types fail
  • Payload format issue
  • Filter or transformation error

Step 4: Test Destination Independently​

Test the destination outside Hooklistener:

curl -X POST https://api.example.com/webhooks \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "test": true,
    "message": "Direct test"
  }'

This helps determine if the issue is with:

  • The destination itself
  • Hooklistener's configuration
  • The webhook payload

Common Issues and Solutions​

Connection Timeout​

Symptoms:

  • Error: "Connection timeout"
  • Destination not responding

Causes:

  • Destination service is down
  • Network connectivity issues
  • Firewall blocking requests

Solutions:

  1. Check destination service status
  2. Verify URL is correct
  3. Test network connectivity
  4. Contact destination service provider

Connection Refused​

Symptoms:

  • Error: "Connection refused"
  • Cannot establish connection

Causes:

  • Service not running
  • Incorrect port
  • Firewall rules

Solutions:

  1. Verify destination service is running
  2. Check port number in URL
  3. Review firewall configuration
  4. Confirm URL is correct

401 Unauthorized​

Symptoms:

  • HTTP 401 response
  • "Unauthorized" error

Causes:

  • Invalid API key/token
  • Expired credentials
  • Wrong authentication header

Solutions:

  1. Verify credentials in Secrets
  2. Check header format (Bearer, Basic, etc.)
  3. Ensure secret name is correct ({{API_KEY}})
  4. Rotate credentials if expired
# Update secret value
# Go to: Organization Settings → Secrets → Edit Secret

403 Forbidden​

Symptoms:

  • HTTP 403 response
  • "Forbidden" error

Causes:

  • Insufficient permissions
  • IP allowlist restrictions
  • API key scope issues

Solutions:

  1. Check API key permissions
  2. Verify account access level
  3. Review IP allowlists
  4. Request necessary scopes

404 Not Found​

Symptoms:

  • HTTP 404 response
  • "Not Found" error

Causes:

  • Incorrect URL
  • Endpoint moved/deleted
  • API version changed

Solutions:

  1. Verify URL is correct
  2. Check destination API documentation
  3. Update URL if endpoint changed
  4. Confirm API version

429 Rate Limited​

Symptoms:

  • HTTP 429 response
  • "Too Many Requests" error

Causes:

  • Exceeded destination rate limits
  • Too many webhooks in short time
  • Burst traffic

Solutions:

  1. Review destination rate limits
  2. Reduce webhook volume if possible
  3. Contact destination for limit increase
  4. Implement webhook throttling

500 Internal Server Error​

Symptoms:

  • HTTP 500 response
  • "Internal Server Error"

Causes:

  • Destination service bug
  • Invalid payload format
  • Destination overloaded

Solutions:

  1. Check destination service status
  2. Review destination logs (if accessible)
  3. Verify payload format
  4. Report to destination service provider
  5. Wait for service recovery

503 Service Unavailable​

Symptoms:

  • HTTP 503 response
  • "Service Unavailable"

Causes:

  • Temporary outage
  • Maintenance window
  • Service overloaded

Solutions:

  1. Check destination status page
  2. Wait for automatic recovery
  3. Circuit breaker will help handle this
  4. Verify maintenance schedule

Resolving Issues​

Step 1: Mark as Work in Progress​

When you start investigating:

  1. Go to Issues → Select Issue
  2. Click "Mark as Work in Progress"
  3. Optionally add investigation notes

This signals to your team that someone is working on it.

Step 2: Fix the Root Cause​

Configuration fixes:

  • Update destination URL
  • Fix authentication headers
  • Correct secret values
  • Adjust transformation code

External fixes:

  • Wait for destination service recovery
  • Contact destination service provider
  • Update API credentials
  • Request permission changes

Step 3: Verify the Fix​

Test that the fix works:

  1. Use the retry feature to re-send failed webhooks:

    • Go to Events → Outgoing
    • Find affected events
    • Click "Retry"

  2. Send a new test webhook

  3. Verify delivery succeeds

  4. Monitor for new occurrences

Step 4: Close the Issue​

Once resolved:

  1. Go to Issues → Select Issue
  2. Click "Close Issue"
  3. Add resolution notes (optional but recommended)
  4. Monitor to ensure no recurrence

Resolution note examples:

  • "Fixed authentication header format"
  • "Updated destination URL after API migration"
  • "Destination service recovered from outage"
  • "Rotated expired API credentials"

Preventing Recurring Issues​

Proactive Monitoring​

  1. Set up alerts:

    • New Issues created
    • Issue occurrence count exceeds threshold
    • Circuit breaker opened

  2. Review regularly:

    • Check Issues dashboard daily
    • Weekly review of closed Issues
    • Monthly trend analysis

  3. Track metrics:

    • Issue frequency by destination
    • Time to resolution
    • Common error types

Configuration Best Practices​

  1. Test before deploying:

    • Test new destinations independently
    • Verify authentication before going live
    • Use staging environments

  2. Monitor destination health:

    • Subscribe to destination status pages
    • Watch for maintenance windows
    • Track destination API changes

  3. Implement redundancy:

    • Multiple destinations for critical webhooks
    • Fallback destinations
    • Alternative notification channels

Documentation​

  1. Document resolutions:

    • Add notes to closed Issues
    • Create runbooks for common problems
    • Share knowledge with team

  2. Track configuration changes:

    • Note when and why changes were made
    • Link to related Issues
    • Document troubleshooting steps

Bulk Issue Management​

When multiple Issues share a root cause:

  1. Identify the pattern:

    • Same destination failing
    • Same error type
    • Same time period

  2. Fix the common problem:

    • Update shared configuration
    • Fix destination service
    • Rotate credentials

  3. Close all related Issues:

    • Add same resolution note
    • Document the common cause
    • Monitor for recurrence

Mass Retry​

After fixing a widespread issue:

  1. Navigate to Events → Outgoing
  2. Filter by:
    • Status: Failed
    • Date range: When issue occurred
    • Destination: Affected destination
  3. Select multiple events
  4. Click "Retry Selected"

Advanced Issue Management​

Issue Lifecycle Workflow​

For critical production issues:

  1. Detection (0-5 minutes)

    • Alert triggered
    • Issue appears in dashboard

  2. Triage (5-15 minutes)

    • Review Issue details
    • Mark as Work in Progress
    • Assign to team member

  3. Investigation (15-60 minutes)

    • Examine affected webhooks
    • Test destination
    • Identify root cause

  4. Resolution (Variable)

    • Implement fix
    • Test resolution
    • Close Issue

  5. Post-Mortem (Within 24 hours)

    • Document what happened
    • Identify preventive measures
    • Update procedures

Escalation Guidelines​

Escalate when:

Immediate escalation:

  • Critical production destination failing
  • High occurrence count (>100 in 1 hour)
  • Security-related issues
  • Data loss risk

Normal escalation:

  • Issue open for >24 hours
  • Unknown root cause
  • Requires external assistance
  • Affects multiple Bridges

Integration with Incident Management​

Connect Hooklistener Issues to your incident management:

Webhook to PagerDuty:

{
  "name": "Critical Issues → PagerDuty",
  "source": {...},
  "destinations": [
    {
      "name": "PagerDuty",
      "url": "https://events.pagerduty.com/v2/enqueue",
      "filters": [
        {"body.occurrence_count": {"$gte": 50}},
        {"body.destination_name": {"$contains": "Production"}}
      ]
    }
  ]
}

Slack notifications:

{
  "name": "New Issues → Slack",
  "type": "slack",
  "webhook_url": "{{SLACK_WEBHOOK_URL}}"
}

Troubleshooting Issue Management​

Issue Not Created​

Expected an Issue but none appeared:

Possible causes:

  • Failures being retried successfully
  • Circuit breaker preventing repeated attempts
  • Filters removing webhooks

Verification:

  • Check Event history for failures
  • Review retry outcomes
  • Verify circuit breaker status

Issue Not Closing​

Issue marked as closed but still showing failures:

Causes:

  • New failures occurring after closure
  • Issue automatically reopened
  • Different Issue with similar errors

Solutions:

  • Verify fix is working
  • Check for new occurrences
  • Review Issue ID to confirm it's the same

Too Many Issues​

Overwhelmed by number of Issues:

Solutions:

  1. Prioritize by impact:

    • Focus on high occurrence count
    • Critical destinations first
    • Production over development

  2. Look for patterns:

    • Group by destination
    • Identify common causes
    • Fix systemic problems

  3. Automate where possible:

    • Set up circuit breakers
    • Implement health checks
    • Use redundant destinations

Best Practices​

Daily Routine​

  1. Morning check:

    • Review open Issues
    • Check new Issues overnight
    • Triage by priority

  2. Throughout the day:

    • Monitor alerts
    • Respond to critical Issues
    • Update Issue statuses

  3. End of day:

    • Close resolved Issues
    • Document pending Issues
    • Plan next day's work

Team Collaboration​

  1. Assign ownership:

    • Assign Issues to team members
    • Use Work in Progress status
    • Update regularly

  2. Communication:

    • Add notes to Issues
    • Share resolution steps
    • Document learnings

  3. Knowledge sharing:

    • Create runbooks
    • Document common Issues
    • Train team members

Metrics to Track​

  1. Issue volume:

    • Total Issues per week
    • Trend over time
    • By destination

  2. Resolution time:

    • Average time to resolution
    • By severity/priority
    • By team member

  3. Recurrence rate:

    • Issues that reopen
    • Common recurring patterns
    • Effectiveness of fixes

Next Steps​

Now that you understand Issue management:

  1. Monitor Circuit Breakers for automatic protection
  2. Configure Retries to reduce transient failures
  3. Track Events to understand webhook patterns
  4. Set up Destinations with reliability in mind

Effective Issue management is key to maintaining reliable webhook workflows. Stay proactive, respond quickly, and always fix root causes rather than symptoms.