Sources

Sources are the entry points for webhooks in Hooklistener. Each Source provides a unique URL where external services can send webhooks, allowing you to receive, inspect, and route webhook data through your Bridges.

Overview

A Source acts as a webhook receiver in your Hooklistener workflow. When you create a Source, Hooklistener generates a unique URL that you can provide to any external service that supports webhooks. Once configured, all webhooks sent to that URL are captured by Hooklistener and can be processed, transformed, filtered, and forwarded to one or more Destinations.

Key features:

• Unique webhook URLs: Each Source has its own dedicated URL
• Security options: Support for signature verification to ensure webhook authenticity
• Deduplication: Automatic detection and handling of duplicate webhooks
• Multiple destinations: Connect a single Source to many Destinations via Bridges
• Real-time monitoring: View incoming webhooks as they arrive
• Event history: Access complete logs of all received webhooks

How Sources Work

When you create a Source, Hooklistener provides you with a URL in this format:

https://api.hooklistener.com/api/v1/s/{source_id}/{optional_path}

You can then:

1. Configure the external service to send webhooks to this URL
2. Set up one or more Bridges that connect this Source to Destinations
3. Monitor incoming webhooks in real-time through the dashboard
4. View event history to debug and understand webhook behavior

Source Types

Hooklistener Sources support different authentication and validation methods:

Standard Sources

• Accept webhooks from any sender
• No authentication required
• Best for: Testing, internal services, trusted environments

Authenticated Sources

• Support webhook signature verification
• Validate requests using HMAC signatures or custom headers
• Best for: Production deployments, third-party integrations, security-critical workflows

Creating a Source

Sources can be created through:

Dashboard (Recommended)

1. Navigate to the Sources page in your dashboard
2. Click "Create Source"
3. Enter a descriptive name (e.g., "GitHub Webhooks", "Stripe Events")
4. Optionally configure authentication settings
5. Click "Create"

Your Source URL will be displayed immediately. Copy it and configure it in your webhook provider.

API

curl -X POST https://api.hooklistener.com/api/v1/bridges \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "GitHub Webhooks",
    "source": {
      "type": "webhook"
    }
  }'

The response includes your Source details and webhook URL.

Source Configuration

Basic Settings

Name: A descriptive identifier for your Source

• Examples: "Production GitHub", "Stripe Payments", "Customer Notifications"
• Helps you identify the Source in your dashboard and logs

Description (Optional): Additional context about the Source

• Purpose of the webhook
• Which external service it's connected to
• Any special handling notes

Authentication Settings

Signature Verification Protect your Source by validating webhook signatures:

1. Configure the signing secret in your Source settings
2. Select the verification method:
   • HMAC-SHA256 (GitHub, Stripe, Shopify style)
   • Custom header validation
   • JWT verification
3. Test the configuration using the test endpoint

When enabled, Hooklistener will reject any webhook with an invalid or missing signature.

Example: GitHub-style verification

// GitHub sends webhooks with this header:
// X-Hub-Signature-256: sha256=<signature>

// Configure your Source with:
{
  "auth_type": "hmac_sha256",
  "secret_header": "X-Hub-Signature-256",
  "secret_key": "your-webhook-secret"
}

Deduplication

Hooklistener can automatically detect and handle duplicate webhooks based on:

Deduplication Keys: Custom fields from the webhook payload

{
  "dedup_enabled": true,
  "dedup_key": "body.event_id"
}

Time Window: How long to remember seen webhooks (default: 1 hour)

{
  "dedup_window": 3600
}

When a duplicate is detected, you can choose to:

• Skip processing entirely (recommended)
• Log and continue
• Flag for review

Monitoring Sources

Real-time Events

View webhooks as they arrive in the Events tab:

• Incoming webhook payloads
• Headers and metadata
• Processing status
• Associated Bridge executions

Source Statistics

Track Source performance:

• Total webhooks received
• Success vs. failure rate
• Average payload size
• Peak traffic times
• Deduplication statistics

Health Monitoring

Hooklistener automatically monitors each Source for:

• Traffic anomalies: Sudden spikes or drops in webhook volume
• Failure patterns: Repeated authentication failures
• Configuration issues: Missing or invalid settings

You'll receive alerts when issues are detected.

Best Practices

Security

1. Always use signature verification in production

   • Prevents unauthorized webhook submissions
   • Validates webhook authenticity
   • Protects against replay attacks

2. Rotate signing secrets regularly

   • Update secrets every 90 days
   • Use Hooklistener's secret rotation features
   • Test after rotation to ensure continuity

3. Monitor authentication failures

   • Set up alerts for repeated failures
   • Investigate unexpected rejection patterns
   • Review logs for security incidents

Organization

1. Use clear, descriptive names

   • Include environment: "GitHub - Production", "GitHub - Staging"
   • Specify purpose: "Stripe - Payment Events", "Stripe - Subscription Changes"
   • Add context: "Customer Portal - User Signups"

2. Document your Sources

   • Add descriptions explaining their purpose
   • Link to external service documentation
   • Note any special configuration requirements

3. Group related Sources

   • Use consistent naming conventions
   • Create separate Sources for different environments
   • Keep test and production Sources isolated

Performance

1. Enable deduplication for reliable senders

   • Reduces redundant processing
   • Improves system efficiency
   • Prevents duplicate actions

2. Monitor payload sizes

   • Large payloads may impact processing time
   • Consider using transformations to reduce data
   • Archive large payloads to external storage

3. Review traffic patterns

   • Identify peak usage times
   • Plan capacity accordingly
   • Optimize Bridge configurations for high traffic

Troubleshooting

Webhooks Not Arriving

Check the Source URL

• Verify the URL in your external service matches exactly
• Include any optional path segments if configured
• Ensure HTTPS (not HTTP) is used

Verify Network Access

• Confirm your external service can reach Hooklistener's servers
• Check for firewall rules blocking outbound webhooks
• Review IP allowlists if configured

Review Authentication

• Disable signature verification temporarily to test connectivity
• Check signing secret matches between services
• Verify header names are correct (case-sensitive)

Authentication Failures

Signature Mismatch

• Confirm signing secret is correct
• Check signature algorithm matches (SHA-256 vs SHA-1)
• Verify payload encoding (UTF-8, base64, etc.)
• Review header format requirements

Missing Headers

• Confirm external service is sending required headers
• Check header names match exactly (case-sensitive)
• Review webhook configuration in external service

Duplicate Detection Issues

Too Many Duplicates Detected

• Review deduplication key configuration
• Adjust time window if webhooks naturally repeat
• Consider disabling for legitimate duplicate events

Duplicates Not Being Caught

• Verify deduplication key exists in payload
• Check key path is correct (e.g., "body.id" vs "id")
• Ensure key values are unique per event

Integration Examples

GitHub Webhooks

{
  "name": "GitHub Repository Events",
  "auth_type": "hmac_sha256",
  "secret_header": "X-Hub-Signature-256",
  "secret_key": "{{GITHUB_WEBHOOK_SECRET}}",
  "dedup_enabled": true,
  "dedup_key": "body.hook_id"
}

Stripe Events

{
  "name": "Stripe Payment Events",
  "auth_type": "hmac_sha256",
  "secret_header": "Stripe-Signature",
  "secret_key": "{{STRIPE_WEBHOOK_SECRET}}",
  "dedup_enabled": true,
  "dedup_key": "body.id"
}

Shopify Orders

{
  "name": "Shopify Order Notifications",
  "auth_type": "hmac_sha256",
  "secret_header": "X-Shopify-Hmac-SHA256",
  "secret_key": "{{SHOPIFY_WEBHOOK_SECRET}}",
  "dedup_enabled": true,
  "dedup_key": "body.id"
}

Next Steps

Now that you understand Sources, learn how to:

1. Create Destinations to forward webhooks
2. Build Bridges to connect Sources and Destinations
3. Set up Filters to route webhooks conditionally
4. Use Transformations to modify webhook payloads
5. Monitor Events to track webhook activity

Sources are the foundation of your webhook automation workflows in Hooklistener. By properly configuring and securing your Sources, you ensure reliable, safe webhook processing from any external service.