Troubleshooting: Common Issues & Solutions

Quick solutions to common webhook integration issues with FetchHook.

#Webhooks Not Arriving

No webhooks appear when fetching, or provider shows webhooks sent but nothing in FetchHook.

Quick Fix

bash

# 1. Verify webhook URL is correct
# Should be: https://webhook.fetchhook.app/{SOURCE_ID}
# NOT the fetch URL: https://api.fetchhook.app/api/v1/{SOURCE_ID}

# 2. Test with cURL
curl -X POST https://webhook.fetchhook.app/{SOURCE_ID} \
  -H "Content-Type: application/json" \
  -d '{"test": "webhook"}'

# 3. Then fetch to verify
curl https://api.fetchhook.app/api/v1/{SOURCE_ID} \
  -H "Authorization: Bearer {YOUR_API_KEY}"

Check provider dashboard for delivery logs and errors
Verify webhook endpoint is enabled in provider settings
Confirm correct events are selected for delivery
Ensure webhook hasn't been disabled due to failures

#401 Unauthorized Error

API returns "Invalid or missing API key" when fetching webhooks.

Fix Authorization

bash

# ✅ Correct format
curl https://api.fetchhook.app/api/v1/{SOURCE_ID} \
  -H "Authorization: Bearer fh_live_abc123..."

# ❌ Common mistakes:

# Missing "Bearer "
-H "Authorization: fh_live_abc123..."

# Wrong header name
-H "X-API-Key: Bearer fh_live_abc123..."

# Using webhook URL as auth
-H "Authorization: Bearer https://webhook.fetchhook.app/..."

Ensure Bearer token format is correct
Check for trailing spaces when copying API key
Verify you're using the API key, not the webhook URL
Confirm API key hasn't been regenerated

#Empty Results

Fetch returns zero webhooks even though you sent test webhooks.

Diagnose Empty Results

bash

# Remove all filters first
curl https://api.fetchhook.app/api/v1/{SOURCE_ID} \
  -H "Authorization: Bearer {YOUR_API_KEY}"

# Check if using wrong source ID
# Your source ID is in the dashboard, verify it matches

# Send a fresh test webhook
curl -X POST https://webhook.fetchhook.app/{SOURCE_ID} \
  -H "Content-Type: application/json" \
  -d '{"test": true}'

# Wait a moment and fetch again
sleep 2
curl https://api.fetchhook.app/api/v1/{SOURCE_ID} \
  -H "Authorization: Bearer {YOUR_API_KEY}"

#Signature Verification Failing

Stripe/GitHub signature validation returns false or fails.

Fix Signature Issues

python

# ✅ Correct: Use original payload
webhook = fetch_webhooks()[0]
payload_str = json.dumps(webhook['payload'], separators=(',', ':'))
signature = webhook['headers']['stripe-signature']

# Verify with exact payload
verify_signature(payload_str, signature, WEBHOOK_SECRET)

# ❌ Wrong: Don't modify payload
payload_str = json.dumps(webhook['payload'], indent=2)  # BREAKS signature!

# ✅ Use exact header names (case-sensitive)
stripe_sig = webhook['headers']['stripe-signature']
github_sig = webhook['headers']['x-hub-signature-256']

Get fresh webhook secret from provider dashboard
Ensure using correct environment (test vs live keys)
Don't modify payload before verification
Use exact header names (case-sensitive)

#429 Rate Limit Exceeded

Too many requests from your IP address. Rate limits: Webhook ingestion 1000/hour, API fetch 100/minute, Provision 1000/hour, Admin endpoints 60/minute.

Handle Rate Limits

python

import time
import requests

def fetch_with_retry(url, headers, max_retries=3):
    for attempt in range(max_retries):
        resp = requests.get(url, headers=headers)

        if resp.status_code == 429:
            retry_after = int(resp.headers.get('Retry-After', 60))
            print(f"Rate limited. Waiting {retry_after}s...")
            time.sleep(retry_after)
            continue

        return resp

    raise Exception("Max retries exceeded")

#413 Payload Too Large

Webhook payload exceeds the 1MB size limit. FetchHook enforces a maximum payload size of 1,048,576 bytes per webhook.

Fix Large Payloads

bash

# Check payload size before sending
PAYLOAD_SIZE=$(wc -c < webhook.json)
if [ "$PAYLOAD_SIZE" -gt 1048576 ]; then
  echo "Error: Payload too large ($PAYLOAD_SIZE bytes > 1MB)"
  exit 1
fi

# Send webhook
curl -X POST https://webhook.fetchhook.app/{SOURCE_ID} \
  -H "Content-Type: application/json" \
  -d @webhook.json

Reduce payload size by removing unnecessary data
Split large payloads into multiple smaller webhooks
Store large data externally and include reference URL
Compress data before sending (if provider supports)

#Duplicate Webhooks

Same webhook processed multiple times. This is normal - providers retry for reliability.

Implement Deduplication

python

# Use event IDs for idempotency
processed_events = set()

def process_webhook(webhook):
    event_id = webhook['event_id']

    if event_id in processed_events:
        print(f"Skipping duplicate: {event_id}")
        return

    # Process webhook
    handle_webhook(webhook)

    # Mark as processed
    processed_events.add(event_id)

# Or use a database for persistence
def is_processed(event_id):
    # Check if event_id exists in database
    return db.exists('processed_webhooks', event_id)

#Connection Timeout

Requests timeout or fail to connect to FetchHook API.

Fix Connection Issues

python

import requests

# Increase timeout
response = requests.get(
    'https://api.fetchhook.app/api/v1/{SOURCE_ID}',
    headers={'Authorization': f'Bearer {API_KEY}'},
    timeout=30  # 30 seconds instead of default
)

# Test connectivity
import socket
try:
    socket.create_connection(('api.fetchhook.app', 443), timeout=5)
    print("✓ Can connect to FetchHook")
except socket.error as e:
    print(f"✗ Connection failed: {e}")

Check network connectivity and firewall rules
Verify DNS resolution for api.fetchhook.app
Increase client timeout (default may be too low)
Check if proxy/VPN is interfering

Agent Protocol Instruction

For debugging: Check provider delivery logs first, test with cURL to isolate integration issues, inspect all headers preserved by FetchHook, verify you're using webhook URL for receiving and fetch URL for retrieving. Common mistakes: wrong URL, missing Bearer token, modifying payload before signature verification, not handling duplicates with event IDs.