How to Troubleshoot BotRefund Not Working After Implementation

When BotRefund doesn't work after implementation, the problem usually lies in one of four places: webhook delivery, API credentials, snippet placement, or network restrictions. The fastest path is to diagnose in that order. Check the dashboard's event log first, then verify credentials, then confirm snippet coverage, and finally inspect firewall rules. These checks cover the vast majority of 'not working' reports.

Start with the Right Diagnostic Order

Jumping straight into code changes or reinstalling the script wastes time. follow this sequence:

1. Open the dashboard event log and look for failed webhooks or timeout errors.
2. Verify that your API key and webhook endpoint are correct and active.
3. Load your checkout pages in a private browser and confirm the BotRefund snippet appears in the page source.
4. Check your firewall or security plugins to see if BotRefund's IPs are blocked.

This order moves from the most common failure point (delivery) to the least common (network). Each step produces concrete evidence you can act on.

1. Check the Event Log in the Dashboard

BotRefund logs every event it receives and every outbound request it attempts. The dashboard's event log is your first stop. Look for entries marked 'failed', 'timeout', or 'error'. These often show a reason code, such as a missing payload field or a connection reset.

If you see failed webhooks, the issue could be that your server is not responding within the expected timeout, or the webhook URL is returning an error status. Copy the failed request and inspect the response code. A 401 or 403 means authentication is wrong; a 5xx indicates a server-side problem on your endpoint.

If there are no log entries at all, BotRefund isn't receiving data. That points to the tracking snippet not firing or being stripped.

2. Verify API Credentials and Webhook Endpoints

BotRefund connects to your store via API keys or a webhook. If the credentials were entered incorrectly during setup, refund claims will fail silently. Double-check:

• The API key is active and has the required permissions (usually read and write for refunds).
• The webhook URL is exactly the one provided, with HTTPS and no trailing slashes.
• You haven't accidentally overwritten the key in a recent plugin update.

Also confirm that the endpoint is publicly reachable. If you're using a staging environment or localhost, BotRefund cannot deliver webhooks to it. Use a site like webhook.site temporarily to see if the BotRefund payload arrives at all.

If you're using a custom integration, review the API documentation to ensure the payload structure matches what your server expects. A missing field like order_id is a common cause of failed calls.

3. Confirm the Tracking Snippet Loads on Every Checkout Page

BotRefund uses a lightweight JavaScript snippet to capture behavioral signals. If the snippet is missing from a checkout page, no data flows, and no refunds can be triggered. Test this by opening your checkout pages in an incognito window and using browser developer tools to search for the BotRefund script.

Common reasons the snippet doesn't load:

• It was added to the homepage only, not to the entire checkout flow.
• Your theme or plugin uses a cache that strips scripts on certain pages.
• A content security policy (CSP) blocks the external script.

Use the 'View Source' option to verify the script tag appears in the raw HTML, not just after page load. Some loaders add the script dynamically, which may be blocked by CSP.

If you're on Shopify or WooCommerce, check that the plugin is enabled and not conflicting with a checkout customizer. A quick way to test is to temporarily disable other scripts and see if BotRefund starts recording events.

4. Review Firewall and IP Whitelist Settings

BotRefund sends webhooks from known IP ranges. If your firewall or security plugin blocks those IPs, requests will be dropped before they reach your server. Check your security logs for blocked requests originating from BotRefund's IP addresses.

If you have a custom whitelist, add BotRefund's IPs. Your dashboard or support documentation should list the current ranges. Also check whether your CDN (like Cloudflare) has any bot protection rules that might flag BotRefund's notifications as spam.

Remember that the webhook is an outbound request from BotRefund to your server. Most firewalls handle inbound traffic, but some egress filters on your server can also block responses. Review both inbound and outbound rules.

5. Common Mistakes That Look Like BotRefund Failures

Even after the four checks above, refunds may still not appear. Look for these common setup errors:

• Test mode left on: BotRefund runs in test mode by default. If you never turned it off, no real claims will be submitted.
• Missing order ID or amount: Your webhook payload must include the order ID and transaction amount. If your custom integration drops a field, the claim is rejected.
• Duplicate installations: If you added the snippet twice, it may fire twice and cause inconsistent sessions. Remove one version.
• Timezone mismatches: If your site uses a timezone far from the ad platform's, conversion timing can appear off, and BotRefund may not match clicks correctly.

These mistakes don't produce errors in the log; they simply prevent claims from being valid. Review your test-mode setting and payload structure if the log is clean.

Key Facts at a Glance

These facts come from the official BotRefund site and help set expectations for what the tool should accomplish once working.

Limitations and When This Advice Doesn't Apply

The troubleshooting steps above cover technical implementation failures. They don't cover cases where BotRefund is working correctly but no refund is due. For example, if the bot click happened before your tracking script was installed, BotRefund has no evidence to claim. Similarly, if your ad platform rejects the claim because the click pattern doesn't meet its invalid-traffic criteria, no technical fix will force a refund.

Also, BotRefund is designed for ad-platform refunds, not for customer refunds on your store. If you're expecting it to handle buyer returns, that's a different feature. Check your plan's scope.

If your site uses a heavily customized checkout that doesn't allow external scripts (e.g., a headless storefront), the standard snippet might not work. In those cases, you may need the universal REST API integration, which requires more developer effort.

Frequently Asked Questions

Why is the dashboard showing no events after I installed the snippet?

No events usually means the snippet isn't firing. Open a page that uses it, view source, and confirm the script tag exists. Also check that the page URL is the one you configured in the dashboard.

My webhook returns 404. What should I do?

Check the exact webhook URL in your backend. A 404 means the endpoint isn't found. Verify that the route is correctly exposed and not protected by authentication middleware that blocks BotRefund's requests.

BotRefund worked for a week then stopped. What changed?

Recent updates to your theme, security plugin, or caching system may have removed the snippet or blocked the IPs. Re-run the four checks, especially the firewall review and snippet presence.

Can I test BotRefund without submitting a real claim?

Yes. Use test mode to simulate events and verify they arrive in the dashboard. This lets you debug without affecting real refunds.

Do I need to whitelist BotRefund's IPs if I use a CDN?

If your CDN blocks requests by IP, yes. Otherwise, the CDN may treat BotRefund's outbound calls as spam. Check your CDN's firewall rules.

What if BotRefund detects bots but the ad platform denies the refund?

Technical troubleshooting won't fix that. You need to provide the evidence BotRefund collects and submit an appeal. Some platforms have specific requirements for invalid-traffic credits.

Your Next Step

If you've gone through all these steps and BotRefund still isn't triggering refunds, run a free bot audit to see exactly what BotRefund detects on your site. The audit will show whether the tracking script captures sessions and highlight any gaps you missed.