Events

Events are the fundamental building blocks of webhook automation in Hooklistener. Every webhook that flows through your Bridges - whether received at a Source or delivered to a Destination - is tracked as an Event, providing complete visibility and auditability of your webhook workflows.

Overview

In Hooklistener, an Event represents a single webhook at a specific point in your automation pipeline. Events capture every detail about the webhook - its payload, headers, metadata, processing status, and outcomes - creating a complete audit trail of all webhook activity.

Key features:

• Complete audit trail: Every webhook is logged with full details
• Incoming and outgoing tracking: Monitor both received and sent webhooks
• Real-time visibility: See Events as they happen
• Searchable history: Query past Events by various criteria
• Delivery tracking: Follow webhooks from arrival to delivery
• Error diagnosis: Access full request/response data for debugging
• Retention: Events stored based on your plan (7-90 days)

Event Types

Incoming Events

Incoming Events are webhooks received at your Sources. When an external service sends a webhook to a Source URL, Hooklistener creates an Incoming Event.

What's captured:

• Request details:
  • HTTP method (POST, PUT, GET, etc.)
  • Full URL and query parameters
  • All request headers
  • Complete payload (body)
  • Request timestamp
• Authentication results:
  • Signature verification status
  • Authentication method used
  • Success or failure details
• Processing outcomes:
  • Deduplication status (new vs duplicate)
  • Filter evaluation results
  • Bridge routing decisions
  • Associated outgoing Events

Example Incoming Event:

{
  "id": "evt_550e8400-e29b-41d4-a716-446655440000",
  "type": "incoming",
  "bridge_id": "bridge_660e8400",
  "source_id": "source_770e8400",
  "timestamp": "2024-01-15T10:30:00Z",
  "method": "POST",
  "url": "https://api.hooklistener.com/api/v1/s/abc123/webhook",
  "headers": {
    "Content-Type": "application/json",
    "X-GitHub-Event": "push",
    "X-Hub-Signature-256": "sha256=..."
  },
  "body": {
    "ref": "refs/heads/main",
    "commits": [...]
  },
  "auth_status": "verified",
  "dedup_status": "new",
  "filter_status": "matched",
  "destinations_triggered": 3
}

Outgoing Events

Outgoing Events are webhooks delivered from Hooklistener to Destinations. For each Destination in a Bridge, Hooklistener creates an Outgoing Event when delivering the webhook.

What's captured:

• Request details:
  • Destination URL and method
  • Headers sent (including transformations)
  • Payload sent (after transformations)
  • Request timestamp
• Response details:
  • HTTP status code
  • Response headers
  • Response body
  • Response time (latency)
• Delivery outcomes:
  • Success or failure status
  • Error messages if failed
  • Retry attempt number
  • Circuit breaker status
• Processing logs:
  • Transformation execution logs
  • Filter evaluation results
  • Timing information

Example Outgoing Event:

{
  "id": "evt_880e8400-e29b-41d4-a716-446655440000",
  "type": "outgoing",
  "bridge_id": "bridge_660e8400",
  "destination_id": "dest_990e8400",
  "incoming_event_id": "evt_550e8400",
  "timestamp": "2024-01-15T10:30:01Z",
  "request": {
    "method": "POST",
    "url": "https://api.example.com/webhooks",
    "headers": {
      "Content-Type": "application/json",
      "Authorization": "Bearer ***"
    },
    "body": {...}
  },
  "response": {
    "status_code": 200,
    "headers": {...},
    "body": {"success": true},
    "latency_ms": 245
  },
  "status": "delivered",
  "retry_count": 0,
  "circuit_breaker_status": "closed"
}

Event Lifecycle

Incoming Event Flow

1. Webhook arrives at Source URL
2. Incoming Event created
   • Request details captured
   • Event ID assigned
   • Timestamp recorded
3. Authentication verified (if configured)
   • Signature validation
   • Results logged in Event
4. Deduplication check (if enabled)
   • Check if webhook already processed
   • Mark as new or duplicate
5. Filters evaluated
   • Bridge-level filters checked
   • Results logged in Event
6. Processing outcome
   • If filters match: Trigger destinations
   • If filters don't match: Mark as filtered
   • If duplicate: Mark as deduplicated

Outgoing Event Flow

1. Destination selected from Bridge configuration
2. Destination filters evaluated
   • Check if destination should receive webhook
   • Log filter results
3. Transformation applied (if configured)
   • Execute transformation code
   • Log execution details and results
4. Outgoing Event created
   • Capture transformed request
   • Record destination details
5. Delivery attempted
   • Send webhook to destination
   • Capture response details
   • Record latency
6. Outcome determined:
   • Success: Mark as delivered
   • Failure: Log error, schedule retry
   • Circuit open: Mark as blocked
7. Retry if needed
   • Schedule next retry attempt
   • Update Event with retry count

Viewing Events

Events Dashboard

Access Events from your Bridge or the main navigation:

Navigate to: Events → Choose Incoming or Outgoing

View options:

• Incoming Events: All webhooks received at Sources
• Outgoing Events: All webhooks delivered to Destinations

Filtering:

• By Bridge
• By Source or Destination
• By status (delivered, failed, pending retry, etc.)
• By date range
• By search query (search payload content)

Sorting:

• By timestamp (default - newest first)
• By status
• By source/destination

Event Details

Click any Event to view complete details:

For Incoming Events:

• Full request (method, URL, headers, body)
• Authentication details
• Deduplication status
• Filter evaluation results
• List of triggered Outgoing Events
• Timeline of processing steps

For Outgoing Events:

• Request sent to destination
• Response received
• Status and error details
• Retry history
• Transformation logs
• Filter evaluation results
• Circuit breaker status
• Related Incoming Event

Real-Time Monitoring

Watch Events as they happen:

Live feed:

• Events appear immediately when received/sent
• Auto-refresh to show latest activity
• Visual indicators for status (success, failure, pending)
• Quick filtering and searching

Use cases:

• Testing new Bridge configurations
• Debugging webhook issues
• Monitoring production traffic
• Verifying transformations work correctly

Event Status

Incoming Event Status

Accepted: Webhook received and accepted for processing

• Authentication passed (if required)
• Not identified as duplicate
• Bridge filters matched

Filtered: Webhook received but not processed

• Bridge-level filters didn't match
• Webhook rejected by filter logic

Deduplicated: Duplicate webhook detected

• Deduplication key matched existing Event
• Within deduplication time window
• Processing skipped

Rejected: Webhook rejected due to error

• Authentication failed
• Invalid payload format
• Bridge inactive

Outgoing Event Status

Delivered: Successfully delivered to destination

• HTTP 2xx response received
• Destination processed webhook
• No retries needed

Failed: Delivery failed after all retries

• All retry attempts exhausted
• Permanent failure (4xx errors except 429)
• Issue may be created

Pending Retry: Awaiting retry attempt

• Initial delivery failed
• Scheduled for next retry
• In retry queue

Circuit Blocked: Blocked by circuit breaker

• Circuit breaker is open
• Too many prior failures
• Will retry when circuit closes

Filtered: Skipped due to destination filters

• Destination-level filters didn't match
• Not an error, intentional routing decision

Searching Events

Basic Search

Search Event payloads for specific content:

Search bar: Enter any text to search

• Searches inside JSON payloads
• Matches against field values
• Case-insensitive by default

Examples:

• [email protected] - Find Events with this email
• payment.succeeded - Find payment success Events
• error - Find Events containing "error"

Advanced Filtering

Combine multiple filters:

By Bridge:

• Select specific Bridge
• See only Events for that Bridge
• Compare across different Bridges

By Status:

• Delivered: Only successful deliveries
• Failed: Only failed deliveries
• Pending: Awaiting retry

By Date:

• Today, Last 7 days, Last 30 days
• Custom date range
• Specific timestamp

By Source/Destination:

• Filter by specific Source
• Filter by specific Destination
• Compare different endpoints

Event Retention

Events are retained based on your plan:

Free Plan: 7 days

• Basic Event history
• Recent troubleshooting

Team Plan: 30 days

• Extended history
• Better audit trail

Enterprise Plan: 90 days (configurable)

• Long-term retention
• Compliance requirements
• Custom retention policies available

After retention period:

• Events are automatically deleted
• Export Events before expiration if needed
• Upgrade plan for longer retention

Exporting Events

Export Event data for external analysis or archival:

Via Dashboard:

1. Navigate to Events
2. Apply desired filters
3. Click "Export"
4. Choose format (JSON, CSV)
5. Download file

Via API:

curl -X GET "https://api.hooklistener.com/api/v1/requests?start_date=2024-01-01&end_date=2024-01-31" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  > events.json

Export includes:

• All Event fields
• Request and response data
• Processing metadata
• Timestamps

Use cases:

• Long-term archival
• Compliance reporting
• External analytics
• Data warehousing
• Audit logs

Event Metrics

Track webhook activity with Event-based metrics:

Volume Metrics

Total Events: Count of all Events

• Incoming Events received
• Outgoing Events delivered
• Trend over time

Events per Bridge: Activity by Bridge

• Identify busiest Bridges
• Monitor traffic patterns
• Capacity planning

Events per Destination: Activity by Destination

• See which destinations receive most webhooks
• Identify integration usage
• Monitor destination load

Performance Metrics

Delivery Success Rate: Percentage of successful deliveries

• Target: >99% for production
• Track by Bridge or Destination
• Identify problematic integrations

Average Latency: Time from receipt to delivery

• End-to-end processing time
• Destination response times
• Identify slow destinations

Retry Rate: Percentage of Events requiring retries

• Higher rate indicates issues
• Track by destination
• Monitor reliability

Error Metrics

Failure Rate: Percentage of permanently failed Events

• Should be minimal (<1%)
• Investigate spikes
• Track by error type

Common Error Types: Most frequent failure reasons

• Authentication failures
• Network timeouts
• 4xx/5xx errors
• Configuration issues

Debugging with Events

Common Debugging Scenarios

Webhook not arriving:

1. Check Incoming Events for your Bridge
2. Look for recent Events from expected source
3. If none: Problem is before Hooklistener (verify Source URL)
4. If present: Check authentication and filter status

Delivery failing:

1. Find the Outgoing Event
2. Check response status code and error message
3. Review request sent (transformation applied?)
4. Test destination endpoint independently
5. Check circuit breaker status

Transformation not working:

1. Locate Outgoing Event
2. View transformation logs
3. Check for JavaScript errors
4. Compare input (Incoming Event) vs output (Outgoing Event)
5. Test transformation with sample payload

Filters not matching:

1. Find the Event (Incoming or Outgoing)
2. Check filter evaluation results
3. View the actual payload
4. Test filter logic with payload
5. Adjust filter conditions

Event Comparison

Compare Events to understand differences:

Same webhook, different outcomes:

• Compare successful vs failed delivery
• Identify what changed
• Spot intermittent issues

Before and after changes:

• Compare Events before/after configuration change
• Verify transformation changes
• Confirm filter adjustments

Best Practices

Monitoring

1. Set up Event alerts

   • Alert on high failure rates
   • Monitor unusual traffic patterns
   • Track critical Bridge activity

2. Review Events regularly

   • Daily check of failed Events
   • Weekly trend analysis
   • Monthly capacity review

3. Use Event data for insights

   • Identify busy times
   • Plan for capacity
   • Optimize configurations

Troubleshooting

1. Start with Event details

   • Always check the actual Event data
   • Don't assume - verify
   • Look at request and response

2. Follow the trail

   • Incoming Event → Outgoing Events
   • See complete flow
   • Identify where issue occurred

3. Use filters effectively

   • Narrow down to relevant Events
   • Filter out noise
   • Focus on problematic patterns

Data Management

1. Export important Events

   • Before retention period ends
   • For compliance/audit purposes
   • For long-term analysis

2. Clean up test Events

   • Use separate test Bridges
   • Filter out test Events from production
   • Deactivate test Bridges when not in use

3. Optimize retention

   • Upgrade plan if more retention needed
   • Export and archive old Events
   • Balance cost vs need

API Reference

List Incoming Events

curl -X GET "https://api.hooklistener.com/api/v1/requests?bridge_id={bridge_id}" \
  -H "Authorization: Bearer YOUR_API_KEY"

List Outgoing Events

curl -X GET "https://api.hooklistener.com/api/v1/webhook-deliveries?bridge_id={bridge_id}" \
  -H "Authorization: Bearer YOUR_API_KEY"

Get Event Details

Incoming:

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

Outgoing:

curl -X GET "https://api.hooklistener.com/api/v1/webhook-deliveries/{delivery_id}/attempts" \
  -H "Authorization: Bearer YOUR_API_KEY"

Retry Failed Event

curl -X POST "https://api.hooklistener.com/api/v1/webhook-deliveries/{delivery_id}/retry" \
  -H "Authorization: Bearer YOUR_API_KEY"

Troubleshooting

Events Not Appearing

For Incoming Events:

• Verify webhook sent to correct Source URL
• Check Bridge is activated
• Review authentication requirements
• Check for network connectivity issues

For Outgoing Events:

• Verify destination is configured
• Check Bridge and destination filters
• Review Bridge activation status
• Check if circuit breaker is open

Missing Event Data

Possible causes:

• Event outside retention period (deleted)
• Wrong Bridge/Source/Destination selected
• Date filter excluding Event
• Search query not matching

Solutions:

• Adjust date range
• Clear filters
• Check all Bridges
• Broaden search query

High Event Volume Issues

Dashboard slow:

• Apply filters to reduce Event count
• Use narrower date ranges
• Search for specific Events

Storage concerns:

• Review retention settings
• Export and archive old Events
• Optimize Bridge configurations
• Consider plan upgrade

Next Steps

Now that you understand Events, explore related features:

1. Build Bridges to route Events efficiently
2. Configure Sources to receive Events
3. Set up Destinations to deliver Events
4. Monitor Issues when Events fail
5. Use Filters to control Event routing

Events provide complete visibility into your webhook workflows. By monitoring and analyzing Events, you gain insights into webhook traffic, identify issues quickly, and maintain reliable webhook automation. Every Event tells a story - from arrival to delivery - giving you the transparency needed to build confident, production-ready webhook integrations.