Skip to main content

Issues

Issues are automatically tracked delivery problems in Hooklistener that help you quickly identify, understand, and resolve webhook failures. Instead of sifting through individual failed events, Issues group related failures together and provide actionable insights for resolution.

Overview​

When webhook deliveries fail, Hooklistener automatically creates and updates Issues to help you track and resolve problems efficiently. Each Issue represents a pattern of failures with similar characteristics, making it easy to focus on fixing root causes rather than individual symptoms.

Key features:

  • Automatic detection: Issues are created automatically from delivery failures
  • Intelligent grouping: Similar failures are grouped into single Issues
  • Status tracking: Track Issues from detection through resolution
  • Occurrence counting: See how many times each Issue occurred
  • Pattern analysis: Understand failure types and causes
  • Resolution workflow: Mark Issues as resolved when fixed
  • Detailed context: Access full error details and affected webhooks

How Issues Work​

Automatic Creation​

When a webhook delivery fails, Hooklistener analyzes the failure:

  1. Failure occurs: Delivery to destination fails
  2. Error analysis: Hooklistener examines error type, destination, and details
  3. Pattern matching: Checks if similar Issue already exists
  4. Issue creation or update:
    • New pattern: Create new Issue
    • Existing pattern: Update existing Issue, increment occurrence count

Issue Grouping​

Issues are grouped by:

  • Destination: Which destination is failing
  • Error type: Network error, HTTP status code, timeout, etc.
  • Error details: Specific error message or code
  • Bridge: Which Bridge is affected

Example grouping:

  • "Destination 'Production API' - 503 Service Unavailable" (one Issue)
  • "Destination 'Production API' - Connection Timeout" (separate Issue)
  • "Destination 'Staging API' - 503 Service Unavailable" (separate Issue)

This intelligent grouping helps you focus on distinct problems rather than being overwhelmed by individual failures.

Issue Lifecycle​

Open → Work in Progress → Closed
  ↑                          ↓
  └──────────────────────────┘

Open: New or active Issue requiring attention

  • Automatically created when failure pattern detected
  • Remains open until you begin working on it

Work in Progress: Issue is being investigated or fixed

  • Manually set when you start working on the Issue
  • Indicates active troubleshooting

Closed: Issue has been resolved

  • Manually closed after fixing root cause
  • Includes resolution timestamp
  • If same failure pattern reoccurs, Issue may reopen

Issue Structure​

Each Issue contains:

Core Information​

Title: Descriptive summary of the problem

  • Example: "Destination 'Slack Alerts' - Connection Timeout"
  • Includes destination name and error type
  • Auto-generated from failure details

Status: Current state (Open, Work in Progress, Closed)

Bridge: Which Bridge is affected

  • Link to Bridge details
  • Shows Source and Destination configuration

Destination: Which specific destination is failing

  • Destination name and type
  • URL and configuration details

Failure Details​

Error Type:

  • Network error (timeout, connection refused)
  • HTTP error (4xx, 5xx status codes)
  • Authentication error
  • Circuit breaker error
  • Transformation error

Error Message: Detailed error description

  • Original error from destination
  • Additional context from Hooklistener
  • Stack traces if applicable

HTTP Status Code: If HTTP error

  • 400 Bad Request
  • 401 Unauthorized
  • 403 Forbidden
  • 404 Not Found
  • 429 Too Many Requests
  • 500 Internal Server Error
  • 502 Bad Gateway
  • 503 Service Unavailable
  • 504 Gateway Timeout

Occurrence Information​

Occurrence Count: How many times this Issue occurred

  • Incremented with each matching failure
  • Helps prioritize critical issues

First Occurrence: When Issue was first detected

  • Timestamp of initial failure
  • Helps understand when problem started

Last Occurrence: Most recent occurrence

  • Timestamp of latest matching failure
  • Indicates if Issue is ongoing or resolved

Resolved At: When Issue was closed (if closed)

  • Timestamp when marked as resolved
  • Useful for tracking resolution time

Viewing Issues​

Issues Dashboard​

Access Issues from the main navigation:

Navigate to: Issues

View options:

  • All Issues: Every Issue regardless of status
  • Open: Only unresolved Issues
  • Work in Progress: Issues actively being fixed
  • Closed: Resolved Issues

Sorting:

  • By last occurrence (default - most recent first)
  • By occurrence count (highest first)
  • By creation date
  • By status

Filtering:

  • By Bridge
  • By Destination
  • By error type
  • By date range

Issue Details​

Click any Issue to view complete details:

Summary Section:

  • Title and status
  • Occurrence count and timeline
  • Bridge and Destination info
  • Error details

Affected Webhooks:

  • List of all webhook deliveries that triggered this Issue
  • Full request/response details
  • Retry attempts
  • Timestamps

Resolution Actions:

  • Update status (Open → Work in Progress → Closed)
  • Add notes about investigation or resolution
  • View related events
  • Retry failed webhooks

Managing Issues​

Updating Issue Status​

Mark as Work in Progress:

When you start investigating or fixing an Issue:

Via Dashboard:

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

Via API:

curl -X PATCH https://api.hooklistener.com/api/v1/issues/{issue_id} \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "work_in_progress"
  }'

Mark as Closed:

When you've fixed the root cause:

Via Dashboard:

  1. Navigate to Issues → Select Issue
  2. Click "Close Issue"
  3. Optionally add resolution notes
  4. Resolved timestamp is automatically set

Via API:

curl -X PATCH https://api.hooklistener.com/api/v1/issues/{issue_id} \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "closed"
  }'

Reopening Issues​

If a closed Issue occurs again:

Automatic reopening:

  • Same failure pattern detected
  • Issue status automatically changes from Closed to Open
  • Occurrence count incremented
  • Last occurrence timestamp updated

Manual reopening:

  • Realized Issue wasn't fully resolved
  • Change status from Closed back to Open or Work in Progress

Common Issue Types​

Network Errors​

Connection Timeout

  • Cause: Destination not responding within timeout period
  • Solutions:
    • Check destination service health
    • Verify network connectivity
    • Increase timeout if legitimate slow responses
    • Review destination capacity

Connection Refused

  • Cause: Destination service not accepting connections
  • Solutions:
    • Verify destination is running
    • Check firewall rules
    • Verify URL and port are correct
    • Review destination logs

DNS Resolution Failure

  • Cause: Cannot resolve destination hostname
  • Solutions:
    • Verify domain name is correct
    • Check DNS server health
    • Wait for DNS propagation if recent change
    • Use IP address temporarily

HTTP Errors​

400 Bad Request

  • Cause: Destination rejected payload format
  • Solutions:
    • Review payload structure
    • Check required fields
    • Validate data types
    • Review destination API documentation
    • Test transformation if used

401 Unauthorized

  • Cause: Authentication failed
  • Solutions:
    • Verify API keys/tokens
    • Check Authorization header format
    • Confirm credentials haven't expired
    • Review secret configuration

403 Forbidden

  • Cause: Authenticated but not authorized
  • Solutions:
    • Check API key permissions
    • Verify account access level
    • Review destination access controls
    • Confirm API key scope

404 Not Found

  • Cause: Destination endpoint doesn't exist
  • Solutions:
    • Verify URL is correct
    • Check for API version changes
    • Review destination configuration
    • Confirm endpoint still exists

429 Too Many Requests

  • Cause: Rate limit exceeded
  • Solutions:
    • Review destination rate limits
    • Reduce webhook volume
    • Implement rate limiting/throttling
    • Contact destination for limit increase

500 Internal Server Error

  • Cause: Destination service error
  • Solutions:
    • Check destination service health
    • Review destination logs
    • Report to destination service provider
    • Wait for service recovery
    • Implement retries

503 Service Unavailable

  • Cause: Destination temporarily unavailable
  • Solutions:
    • Wait for service recovery
    • Check destination status page
    • Verify maintenance windows
    • Circuit breaker will help handle this

504 Gateway Timeout

  • Cause: Upstream service timeout
  • Solutions:
    • Check destination infrastructure
    • Review proxy/load balancer configuration
    • Increase timeout if appropriate
    • Optimize destination processing

Configuration Errors​

Invalid Transformation

  • Cause: Transformation code has errors
  • Solutions:
    • Review transformation syntax
    • Check transformation logs
    • Test with sample payload
    • Fix JavaScript errors

Filter Mismatch

  • Cause: All webhooks filtered out
  • Solutions:
    • Review filter logic
    • Test filters with real payloads
    • Verify field paths are correct
    • Adjust filter conditions

Circuit Breaker Open

  • Cause: Too many failures triggered circuit breaker
  • Solutions:
    • Fix underlying destination issue
    • Wait for automatic recovery
    • Reset circuit breaker if destination fixed
    • Review circuit breaker thresholds

Issue Workflows​

Investigation Workflow​

  1. Identify Issue: Review Issues dashboard
  2. Prioritize: Sort by occurrence count or recency
  3. Mark as WIP: Update status to Work in Progress
  4. Analyze Details:
    • Review error messages
    • Check affected webhooks
    • Examine request/response data
    • Test destination independently
  5. Diagnose Root Cause:
    • Network issue?
    • Configuration error?
    • Destination problem?
    • Authentication issue?
  6. Implement Fix:
    • Update configuration
    • Fix destination
    • Adjust transformation
    • Correct authentication
  7. Test Resolution:
    • Retry affected webhooks
    • Monitor for new occurrences
    • Verify deliveries succeed
  8. Close Issue: Mark as Closed with notes

Bulk Resolution Workflow​

For multiple related Issues:

  1. Identify pattern: Multiple Issues with same root cause
  2. Fix common problem: Update shared configuration or fix destination
  3. Test thoroughly: Ensure fix addresses all Issues
  4. Close Issues: Mark all related Issues as resolved
  5. Monitor: Watch for any recurrence

Monitoring and Alerting​

Dashboard Summary​

Quick overview of Issue health:

Issue Statistics:

  • Total open Issues
  • Issues in Work in Progress
  • Issues resolved in last 7/30 days
  • Highest occurrence count
  • Most frequent destinations with Issues

Trends:

  • Issues opened over time
  • Issues closed over time
  • Average time to resolution
  • Most common error types

Issue Alerts​

Configure notifications for new Issues:

Alert conditions:

  • New Issue created
  • Issue occurrence count exceeds threshold
  • Issue remains open for X days
  • High-priority destination having issues

Notification channels:

  • Email
  • Slack
  • Discord
  • Telegram
  • Webhook

Best Practices​

Proactive Issue Management​

  1. Review Issues daily

    • Check for new Issues each day
    • Prioritize by occurrence count
    • Address high-impact Issues first

  2. Set up alerts

    • Get notified immediately of new Issues
    • Configure threshold alerts for high occurrence counts
    • Monitor critical destinations closely

  3. Track resolution time

    • Aim to resolve Issues quickly
    • Document resolution steps
    • Learn from patterns

Investigation​

  1. Start with error details

    • Read error messages carefully
    • Check HTTP status codes
    • Review stack traces

  2. Examine affected webhooks

    • Look at request payloads
    • Check response data
    • Identify commonalities

  3. Test independently

    • Reproduce the issue outside Hooklistener
    • Test destination endpoint directly
    • Verify credentials and configuration

Resolution​

  1. Fix root cause, not symptoms

    • Don't just retry failed webhooks
    • Address underlying problem
    • Verify fix resolves Issue pattern

  2. Document resolution

    • Add notes to Issue
    • Update configuration docs
    • Share knowledge with team

  3. Monitor after fixing

    • Watch for Issue recurrence
    • Verify sustained resolution
    • Adjust if needed

API Reference​

List Issues​

curl -X GET https://api.hooklistener.com/api/v1/issues \
  -H "Authorization: Bearer YOUR_API_KEY"

Query parameters:

  • status: Filter by status (open, work_in_progress, closed)
  • page: Page number
  • page_size: Items per page

Response:

{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "bridge_id": "660e8400-e29b-41d4-a716-446655440001",
      "destination_id": "770e8400-e29b-41d4-a716-446655440002",
      "status": "open",
      "error_type": "http_error",
      "error_code": "503",
      "error_message": "Service Unavailable",
      "occurrence_count": 15,
      "first_occurrence_at": "2024-01-15T10:00:00Z",
      "last_occurrence_at": "2024-01-15T10:30:00Z",
      "resolved_at": null
    }
  ],
  "pagination": {
    "current_page": 1,
    "page_size": 10,
    "total_pages": 3,
    "total_records": 25
  }
}

Get Issue Details​

curl -X GET https://api.hooklistener.com/api/v1/issues/{issue_id} \
  -H "Authorization: Bearer YOUR_API_KEY"

Update Issue Status​

curl -X PATCH https://api.hooklistener.com/api/v1/issues/{issue_id} \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "closed"
  }'

Troubleshooting​

Too Many Issues​

Problem: Overwhelmed by number of Issues

Solutions:

  1. Filter by priority:

    • Sort by occurrence count
    • Focus on high-impact destinations
    • Address patterns, not individual Issues

  2. Identify common causes:

    • Look for shared error types
    • Fix systemic problems
    • Batch-resolve related Issues

  3. Set up better monitoring:

    • Use circuit breakers
    • Implement health checks
    • Proactive alerting

Issues Not Being Created​

Problem: Failures occurring but no Issues appearing

Possible causes:

  • Failures being retried successfully
  • Circuit breakers preventing repeated failures
  • Filters removing all webhooks

Verification:

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

False Issues​

Problem: Issues created for expected behavior

Examples:

  • 404 errors for intentionally missing resources
  • Rate limiting during expected traffic spikes
  • Maintenance window failures

Solutions:

  • Adjust Bridge configuration
  • Use filters to exclude expected failures
  • Schedule maintenance windows
  • Temporarily disable Bridges during maintenance

Next Steps​

Now that you understand Issues, explore related features:

  1. Monitor Circuit Breakers for automatic failure protection
  2. Configure Retries to reduce transient failures
  3. Track Events to see individual webhook deliveries
  4. Build Bridges with reliability in mind
  5. Set up Destinations to prevent common issues

Issues provide critical visibility into webhook delivery problems, helping you maintain reliable webhook workflows. By actively monitoring and resolving Issues, you ensure your webhook integrations operate smoothly and efficiently.