Creating Sources

This guide walks you through creating your first Source in Hooklistener - the entry point for receiving webhooks from external services. By the end, you'll have a working Source URL ready to receive webhooks.

What You'll Learn

How to create a Source via the dashboard
How to create a Source via the API
How to configure authentication and security
How to test your Source with real webhooks
Common setup patterns for popular services

Prerequisites

A Hooklistener account
Basic understanding of Sources
(Optional) API key if using the API

Creating a Source via Dashboard

Step 1: Navigate to Sources

Log in to your Hooklistener dashboard at app.hooklistener.com
Click "Bridges" in the left sidebar
Click "Create Bridge" button

Step 2: Name Your Source

Give your Source a descriptive name that indicates:

What service will send webhooks (e.g., "GitHub", "Stripe", "Shopify")
The environment (e.g., "Production GitHub", "Staging Stripe")
The purpose (e.g., "GitHub - Repository Events", "Stripe - Payment Webhooks")

Good examples:

GitHub Production - Main Repository
Stripe Production - Payment Events
Shopify Staging - Order Notifications

Why it matters: You'll see this name in logs, dashboards, and error messages. Clear names make debugging easier.

Step 3: Source URL Generated

Once created, Hooklistener generates a unique webhook URL for your Source:

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

Example:

https://api.hooklistener.com/api/v1/s/abc123def456/webhook

Important: Copy this URL immediately - you'll need it to configure your webhook provider.

Step 4: Configure Authentication (Recommended)

For production Sources, always enable webhook signature verification:

In your Source settings, click "Enable Authentication"
Choose the verification method:
- HMAC-SHA256 (most common - GitHub, Stripe, Shopify)
- Custom Header (for services with custom auth)
- JWT Verification (for JWT-signed webhooks)
For HMAC-SHA256:
- Enter the Secret Key (from your webhook provider)
- Specify the Signature Header Name (e.g., X-Hub-Signature-256 for GitHub)
- Choose the Hash Algorithm (usually SHA-256)
Store the secret:
- Click "Save to Secrets"
- Enter a secret name (e.g., GITHUB_WEBHOOK_SECRET)
- This stores it securely and lets you reference it as {{GITHUB_WEBHOOK_SECRET}}

Step 5: Configure Deduplication (Optional)

If your webhook provider might send duplicate events:

Enable "Deduplication"
Specify the Deduplication Key - the JSON path to a unique identifier:
- GitHub: body.hook_id or body.delivery
- Stripe: body.id
- Generic: body.event_id or body.id
Set the Time Window (default: 1 hour)
- How long to remember seen webhooks
- Adjust based on your needs

Step 6: Test Your Source

Before connecting it to a live service, test your Source:

Copy your Source URL
Use a tool like curl or Postman to send a test webhook:

curl -X POST https://api.hooklistener.com/api/v1/s/{your_source_id}/webhook \
  -H "Content-Type: application/json" \
  -d '{
    "test": true,
    "message": "Hello from Hooklistener!"
  }'

Go to Events → Incoming to see your test webhook
Verify it appears with correct payload

Step 7: Configure Your Webhook Provider

Now configure the external service to send webhooks to your Source URL:

GitHub:

Go to your repository → Settings → Webhooks
Click "Add webhook"
Paste your Source URL in "Payload URL"
Enter your secret in "Secret"
Select events to subscribe to
Click "Add webhook"

Stripe:

Go to Stripe Dashboard → Developers → Webhooks
Click "Add endpoint"
Paste your Source URL
Select events to listen for
Click "Add endpoint"
Copy the signing secret to your Source authentication settings

Shopify:

Go to Shopify Admin → Settings → Notifications → Webhooks
Click "Create webhook"
Select event type
Paste your Source URL
Select "JSON" format
Click "Save"

Creating a Source via API

Step 1: Get Your API Key

Navigate to Organization Settings → API Keys
Create a new API key if you don't have one
Copy the key (starts with hklst_)

Step 2: Create the Bridge with Source

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

Response:

{
  "id": "bridge_abc123",
  "name": "GitHub Production Repository",
  "source": {
    "id": "source_def456",
    "name": "GitHub Events",
    "url": "https://api.hooklistener.com/api/v1/s/def456/webhook",
    "type": "webhook"
  },
  "destinations": [],
  "created_at": "2024-01-15T10:30:00Z"
}

Step 3: Add Authentication

Update the Source with authentication:

curl -X PUT https://api.hooklistener.com/api/v1/sources/source_def456 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "auth_type": "hmac_sha256",
    "secret_header": "X-Hub-Signature-256",
    "secret_key": "{{GITHUB_WEBHOOK_SECRET}}"
  }'

Step 4: Add Deduplication

curl -X PUT https://api.hooklistener.com/api/v1/sources/source_def456 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "dedup_enabled": true,
    "dedup_key": "body.hook_id",
    "dedup_window": 3600
  }'

Common Source Configurations

GitHub Webhooks

Dashboard Settings:

Name: GitHub - Repository Events
Authentication: HMAC-SHA256
Secret Header: X-Hub-Signature-256
Secret Key: {{GITHUB_WEBHOOK_SECRET}}
Deduplication Key: body.hook_id

GitHub Configuration:

Payload URL: Your Source URL
Content type: application/json
Secret: Same value as GITHUB_WEBHOOK_SECRET
SSL verification: Enable
Events: Choose relevant events (push, pull_request, issues, etc.)

Stripe Webhooks

Dashboard Settings:

Name: Stripe - Payment Events
Authentication: HMAC-SHA256
Secret Header: Stripe-Signature
Secret Key: {{STRIPE_WEBHOOK_SECRET}}
Deduplication Key: body.id

Stripe Configuration:

Endpoint URL: Your Source URL
Events: Select events (payment_intent.succeeded, charge.failed, etc.)
API version: Latest
Copy signing secret to your Hooklistener secret

Shopify Webhooks

Dashboard Settings:

Name: Shopify - Order Events
Authentication: HMAC-SHA256
Secret Header: X-Shopify-Hmac-SHA256
Secret Key: {{SHOPIFY_WEBHOOK_SECRET}}
Deduplication Key: body.id

Shopify Configuration:

URL: Your Source URL
Format: JSON
API version: Latest
Event: orders/create, orders/updated, etc.

Generic REST API

Dashboard Settings:

Name: Internal Service - Notifications
Authentication: Custom Header
Header Name: X-API-Key
Header Value: {{INTERNAL_API_KEY}}

Service Configuration: Send POST requests with your API key in the header:

curl -X POST https://api.hooklistener.com/api/v1/s/{source_id}/webhook \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"event": "user.created", "data": {...}}'

Testing Your Source

Test 1: Basic Connectivity

Verify webhooks reach your Source:

curl -X POST https://api.hooklistener.com/api/v1/s/{source_id}/webhook \
  -H "Content-Type: application/json" \
  -d '{"test": "connectivity"}'

Check Events → Incoming to confirm receipt.

Test 2: Authentication

Test that authentication is working:

Without signature (should fail):

curl -X POST https://api.hooklistener.com/api/v1/s/{source_id}/webhook \
  -H "Content-Type: application/json" \
  -d '{"test": "auth"}'

Expected: Authentication failure in Events log.

With valid signature: Use your webhook provider's test feature or a signature generation tool.

Expected: Successful authentication in Events log.

Test 3: Deduplication

Send the same webhook twice within the deduplication window:

# First request
curl -X POST https://api.hooklistener.com/api/v1/s/{source_id}/webhook \
  -H "Content-Type: application/json" \
  -d '{"id": "test-123", "data": "first"}'

# Second request (duplicate)
curl -X POST https://api.hooklistener.com/api/v1/s/{source_id}/webhook \
  -H "Content-Type: application/json" \
  -d '{"id": "test-123", "data": "second"}'

Check Events: Second request should be marked as "deduplicated".

Test 4: Real Webhook

Trigger a real webhook from your service:

GitHub: Make a commit or open a pull request Stripe: Create a test payment Shopify: Create a test order

Monitor Events → Incoming in real-time to see the webhook arrive.

Troubleshooting

Webhooks Not Arriving

Check Source URL:

Verify URL is copied exactly from Hooklistener
Ensure it's configured in your webhook provider
Confirm no typos or extra characters

Check Service Configuration:

Verify webhook is enabled in external service
Check selected events include what you're testing
Ensure service can reach Hooklistener (firewall, network)

Check Event Logs:

Look in Events → Incoming for rejected webhooks
Check authentication failures
Review error messages

Authentication Failures

Verify Secret:

Confirm secret in Hooklistener matches webhook provider
Check for leading/trailing spaces
Ensure secret isn't expired or rotated

Check Header Name:

Header names are case-sensitive
Verify exact header name from provider docs
Common: X-Hub-Signature-256, Stripe-Signature, X-Shopify-Hmac-SHA256

Review Hash Algorithm:

Confirm SHA-256 vs SHA-1 vs other
Match the algorithm your provider uses

Deduplication Issues

Too Many Duplicates:

Check if deduplication key path is correct
Verify key exists in all webhooks
Adjust time window if needed

Not Catching Duplicates:

Verify deduplication key is truly unique per event
Check that key values match for duplicate webhooks
Ensure within time window

Best Practices

Security

Always use authentication in production
- Test without auth, but enable before going live
- Use strong, random webhook secrets
- Never share secrets in public repositories
Rotate secrets regularly
- Update secrets every 90 days
- Use Hooklistener Secrets for easy rotation
- Test after rotation
Monitor authentication failures
- Set up alerts for repeated failures
- Investigate suspicious patterns
- Review regularly

Organization

Use clear, descriptive names
- Include service name and environment
- Add purpose or event type
- Make it easy to identify in logs
Separate environments
- Create different Sources for dev/staging/production
- Use different secrets for each environment
- Test in staging before production
Document your Sources
- Add descriptions to Sources
- Note webhook provider details
- Link to external service documentation

Reliability

Test thoroughly
- Test connectivity first
- Verify authentication works
- Confirm deduplication if enabled
- Send real webhooks before going live
Monitor your Sources
- Watch incoming event rates
- Set up alerts for drops in traffic
- Review authentication failures
Plan for scale
- Consider webhook volume
- Monitor performance
- Upgrade plan if needed

Next Steps

Now that you've created a Source, you'll want to:

Create Destinations where webhooks should be forwarded
Build a Bridge to connect your Source to Destinations
Set up Filters to route webhooks conditionally
Use Transformations to modify payloads

Your Source is now ready to receive webhooks! The next step is creating Destinations and connecting them together with a Bridge.

What You'll Learn​

Prerequisites​

Creating a Source via Dashboard​

Step 1: Navigate to Sources​

Step 2: Name Your Source​

Step 3: Source URL Generated​

Step 4: Configure Authentication (Recommended)​

Step 5: Configure Deduplication (Optional)​

Step 6: Test Your Source​

Step 7: Configure Your Webhook Provider​

Creating a Source via API​

Step 1: Get Your API Key​

Step 2: Create the Bridge with Source​

Step 3: Add Authentication​

Step 4: Add Deduplication​

Common Source Configurations​

GitHub Webhooks​

Stripe Webhooks​

Shopify Webhooks​

Generic REST API​

Testing Your Source​

Test 1: Basic Connectivity​

Test 2: Authentication​

Test 3: Deduplication​

Test 4: Real Webhook​

Troubleshooting​

Webhooks Not Arriving​

Authentication Failures​

Deduplication Issues​

Best Practices​

Security​

Organization​

Reliability​

Next Steps​

What You'll Learn

Prerequisites

Creating a Source via Dashboard

Step 1: Navigate to Sources

Step 2: Name Your Source

Step 3: Source URL Generated

Step 4: Configure Authentication (Recommended)

Step 5: Configure Deduplication (Optional)

Step 6: Test Your Source

Step 7: Configure Your Webhook Provider

Creating a Source via API

Step 1: Get Your API Key

Step 2: Create the Bridge with Source

Step 3: Add Authentication

Step 4: Add Deduplication

Common Source Configurations

GitHub Webhooks

Stripe Webhooks

Shopify Webhooks

Generic REST API

Testing Your Source

Test 1: Basic Connectivity

Test 2: Authentication

Test 3: Deduplication

Test 4: Real Webhook

Troubleshooting

Webhooks Not Arriving

Authentication Failures

Deduplication Issues

Best Practices

Security

Organization

Reliability

Next Steps