Troubleshooting

This guide covers common issues and their solutions.

Session Issues

Session Not Created

Problem: Clicking “Create Session” shows an error.

Solutions:

  1. Not logged in: Anonymous users may have session creation disabled. Log in or register.
  2. Network error: Check your internet connection.
  3. Server error: Try again in a few minutes. Check the status page for known issues.

Session Expired

Problem: Your session shows as “Expired” or webhooks aren’t being received.

Solutions:

  1. Check session TTL: Sessions expire based on their configured lifetime.
    • Anonymous: 24 hours (configurable)
    • Authenticated: Infinite by default
  2. Extend session: Go to Dashboard, find the session, and update settings.
  3. Create new session: If expired, create a new session.

Multiple Sessions for Same Webhook

Problem: You want multiple sessions to receive webhooks from the same URL.

Solution: This isn’t supported. Each webhook URL maps to exactly one session. Create a new session to get a new URL.

Webhook Issues

Webhooks Not Received

Problem: You sent a webhook but don’t see it in the inspector.

Solutions:

  1. Check the URL: Ensure you’re using the correct webhook URL:

    https://webhook-tester.appfactory.workers.dev/api/webhook/{session-id}

    The session ID must match exactly.

  2. Verify session is active: Check Dashboard for session status.

  3. Send a test webhook:

    curl -X POST https://webhook-tester.appfactory.workers.dev/api/webhook/{your-session-id} \
  -H "Content-Type: application/json" \
  -d '{"test": true, "timestamp": "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"}'

  4. Check headers: The Content-Type header should match your payload format.

  5. Firewall/Network: Ensure your network allows HTTPS to webhook-tester.appfactory.workers.dev.

Missing Headers

Problem: Expected headers aren’t showing in the inspector.

Solution: Some headers are filtered for security:

  • Host: Always shows the webhook tester domain
  • X-Forwarded-*: Proxied headers may be normalized
  • CF-*: Cloudflare-specific headers filtered

Large Payloads

Problem: Webhook payload is truncated.

Solution: Maximum payload size is 10 MB. For larger payloads:

  • Split into multiple webhooks
  • Use external storage (S3, etc.) and send a reference URL

Binary Data Not Displayed

Problem: Binary payload shows as gibberish or empty.

Solution: Binary payloads are base64 encoded in the inspector. Decode using:

echo "base64_encoded_data" | base64 -d > output.bin

Authentication Issues

Cannot Log In

Problem: Login fails with “Invalid credentials”.

Solutions:

  1. Check email verification: Ensure your email is verified. Check spam folder.
  2. Password: Verify correct password. Reset if needed via Forgot Password.
  3. Account locked: After 5 failed attempts, accounts are locked for 30 minutes.
  4. OAuth: Try GitHub or Google login instead.

Email Verification Not Received

Problem: Verification email didn’t arrive.

Solutions:

  1. Check spam/junk folder
  2. Wait 5 minutes: Sometimes emails are delayed
  3. Request resend: Log in and request a new verification email
  4. Whitelist: Add noreply@webhook-tester.app to your contacts

Account Locked

Problem: Account locked after failed login attempts.

Solution: Wait 30 minutes, then try again. Or use password reset to unlock immediately:

  1. Go to Forgot Password
  2. Enter your email
  3. Check email for reset link
  4. Set new password

API Key Issues

Invalid API Key

Problem: API returns 401 Unauthorized.

Solutions:

  1. Check key format: Must include whpk_live_ prefix
  2. Verify key exists: Check API Keys page
  3. Key revoked: Create a new key if revoked
  4. Copy error: Ensure no extra spaces or newlines

Permission Denied

Problem: API returns 403 Forbidden.

Solution: Your key lacks required permissions. Create a new key with appropriate level:

  • read: View sessions/webhooks
  • write: Create sessions
  • admin: Full access

Key Not Loading

Problem: API Keys page shows error.

Solutions:

  1. Log out and back in: Session may have expired
  2. Clear browser cache: Hard refresh (Cmd+Shift+R)
  3. Check console: Open browser DevTools for error details

WebSocket Issues

Real-Time Updates Not Working

Problem: Webhooks don’t appear in real-time.

Solutions:

  1. Check WebSocket connection: Inspector shows connection status
  2. Firewall: WebSocket may be blocked. Try on different network
  3. Browser support: Use modern browser (Chrome, Firefox, Safari, Edge)
  4. Reconnect: Refresh the page to reconnect

WebSocket Disconnected

Problem: Inspector shows “Disconnected”.

Solutions:

  1. Automatic reconnection: The inspector attempts to reconnect every 5 seconds
  2. Refresh page: If not reconnecting, refresh
  3. Check network: Ensure stable internet connection

Performance Issues

Slow Dashboard

Problem: Pages load slowly.

Solutions:

  1. Large dataset: If you have many sessions/webhooks, use search/filter
  2. Browser: Clear cache or try different browser
  3. Network: Check internet speed

Session List Not Loading

Problem: Dashboard shows loading spinner indefinitely.

Solutions:

  1. Check auth token: Log out and back in
  2. Network tab: Check for failed requests in DevTools
  3. Console errors: Look for JavaScript errors

CORS Issues

Browser Console Shows CORS Error

Problem: Access-Control-Allow-Origin error in console.

Solution: This shouldn’t happen on production. If you see this:

  1. Clear cache: Hard refresh
  2. Report bug: This is likely a configuration issue - contact support

General Tips

Debug Checklist

When something isn’t working:

  1. ✅ Are you logged in?
  2. ✅ Is the session active?
  3. ✅ Is the webhook URL correct (copy-paste, no typos)?
  4. ✅ Is the Content-Type header correct?
  5. ✅ Check browser console for errors
  6. ✅ Try incognito/private window
  7. ✅ Try different browser
  8. ✅ Try different network (mobile hotspot)

Getting Help

If your issue isn’t covered here:

  1. Check other documentation pages
  2. Contact support through the app
  3. Provide details:
    • What you were doing
    • What you expected
    • What actually happened
    • Browser/network info
    • Error messages (exact text)
← Back to Documentation