Troubleshooting Common Issues

CLI Connection Issues

If the CLI cannot connect to ReqPour, check these common causes:

"Authentication required" error: Your login session may have expired. Run npx reqpour login to re-authenticate. If you are using REQPOUR_TOKEN, verify the token is correct and has not been revoked.

"WebSocket connection failed" error: This usually means a network issue is preventing the WebSocket connection. Check your internet connection. If you are behind a corporate firewall or proxy, WebSocket connections may be blocked — ask your network administrator to allow outbound connections to wss://api.reqpour.com.

"Connection refused" on relay: This means the CLI connected to ReqPour successfully but cannot reach your local server. Verify your local server is running and the port matches the --to URL. Common mistake: your server is on port 3001 but you specified port 3000.

Slow relay responses: If the relay seems slow, check your internet connection latency. The round trip goes: provider -> ReqPour cloud -> WebSocket -> your machine -> localhost -> back. If latency is consistently above 500ms, consider self-hosting ReqPour closer to your location.

Webhooks Not Arriving

If webhook requests are not appearing in the ReqPour dashboard:

Check the endpoint URL: Verify the URL you configured in the webhook provider exactly matches your ReqPour endpoint URL. Common mistakes include missing the https:// prefix, extra trailing slashes, or typos in the subdomain.

Check the provider's webhook logs: Most providers (Stripe, GitHub, Shopify) show webhook delivery attempts in their dashboard. If the provider shows a delivery failure, the issue is between the provider and ReqPour. If the provider shows no delivery attempts, the webhook was never triggered.

Verify the webhook is enabled: Some providers require you to enable webhooks after configuring them. Check that the webhook subscription is active, not paused or disabled.

Check event selection: If you selected specific events in the provider's webhook configuration, make sure the event you are triggering is actually selected. For example, Stripe will not send payment_intent.succeeded events if you only subscribed to checkout.session.completed.

Try a manual test: Use curl to send a test request to your endpoint and verify it appears in the dashboard:

curl -X POST https://abc123.reqpour.com/test \
  -H "Content-Type: application/json" \
  -d '{"test": true}'

Relay Not Forwarding

If requests appear in the dashboard but are not being forwarded to your local server:

Verify the relay is running: Check your terminal for the relay process. It should show "Connected" and be waiting for requests. If the relay crashed, restart it.

Check the target URL: The --to URL must be reachable from your machine. Test it with curl:

curl -X POST http://localhost:3000/api/webhooks \
  -H "Content-Type: application/json" \
  -d '{"test": true}'

If curl cannot reach your server, the relay will not be able to either.

Check for middleware blocking: Common culprits include CSRF protection (webhook endpoints should be excluded), authentication middleware (webhooks are unauthenticated by design), and rate limiting. Check your server's logs for rejected requests.

Path mismatch: The relay forwards the request path from the original URL. If a request arrives at https://abc123.reqpour.com/stripe/webhooks, the relay sends it to http://localhost:3000/stripe/webhooks. Make sure this path matches a route in your application.

Signature Verification Failures

Webhook signature verification failures are the most common issue developers face. Here is a systematic debugging approach:

Verify you are using the correct secret: Each provider has a specific webhook signing secret. For Stripe, this is different from your API secret key. For GitHub, it is the secret you entered when creating the webhook. Double-check the secret value in your environment variables.

Check body parsing order: Signature verification must happen on the raw, unparsed body. If your framework parses the body before your verification code runs, the re-serialized body may have different bytes. See the framework-specific guides for correct raw body access patterns.

Compare computed vs received: Log both the signature you computed and the one from the header:

console.log('Received:', req.headers['x-signature']);
console.log('Computed:', computedHash);
console.log('Body length:', rawBody.length);
console.log('Body preview:', rawBody.substring(0, 100));

Check the encoding: Some providers use hex encoding (Stripe, GitHub), others use base64 (Shopify). Mismatched encoding means the hashes will never match even if the computation is correct.

Check the signed payload format: Some providers sign just the body, others sign a combination of timestamp and body. Stripe signs timestamp + "." + body, Slack signs "v0:" + timestamp + ":" + body. Consult the provider's documentation for the exact format.

Performance and Timeout Issues

If webhook providers report timeouts or your handler is too slow:

Respond quickly: Most providers have a 3-10 second timeout. If your handler does any significant processing (database queries, API calls, email sends), respond immediately and process asynchronously. Return a 200 status right away, then queue the actual work.

Check for blocking operations: Synchronous database queries, external API calls, or file system operations in your webhook handler block the response. Move these to a background job or use async patterns.

Monitor latency: The ReqPour dashboard shows the response time for each request. If times are consistently above 2 seconds, your handler needs optimization. The relay adds 20-100ms of overhead — if the total time is much higher, the bottleneck is in your handler code.

Reduce payload processing: For large payloads, extract only the fields you need rather than processing the entire object. Defer full parsing to the background job.

If you are experiencing intermittent timeouts, check your database connection pool. Under load, all connections might be in use, causing new queries to wait. Increase the pool size or use connection pooling middleware.