How Webhooks from My ESP Were Blocked by WordPress Rewrite Rules and the Rewrite Exception That Restored Real-Time Syncs
4 min read
I thought I had everything set up just right. My email service provider (ESP) was configured, my WordPress site looked great, and my automation flows were all in place. Then I noticed something strange—webhooks from my ESP weren’t coming through. My real-time syncs were broken! What happened? Let’s dive into the mystery and see what was going on.
TLDR:
WordPress rewrite rules were blocking incoming webhook requests from my ESP. These rules didn’t recognize the custom endpoint I set up. As a result, nothing reached my site. The fix was adding a rewrite exception for the webhook path so WordPress wouldn’t get in the way. After that, real-time syncs started working again!
What is a webhook, anyway?
A webhook is like a little messenger. When something happens in one app—like a new subscriber in your ESP—it sends a payload to a URL you give it. That URL belongs to another app—like WordPress. No need to hit refresh or wait five minutes for a sync. It’s fast and automatic.
Imagine you’re baking. When your oven timer is done, it sends a loud ding! to alert you. That’s kind of what a webhook does—alerts your website something just happened elsewhere.
The problem: Ghosted by my webhooks
My ESP let me define where to send those webhook messages. I gave it a clean, simple URL on my WordPress site:
https://mysite.com/webhook-handler/
Everything looked fine. Until I realized that none of those webhooks were reaching my site. I looked at the logs from my ESP—it showed “200 OK” responses, but I wasn’t seeing any data. Totally confusing.
I checked my webhook handler script. It worked perfectly when accessed directly in the browser. But somehow, when the ESP sent data, my site acted like… nothing happened. No post-processing, no logging. Just silence.
The detective work begins
I rolled up my sleeves and turned on WordPress debugging. Then I threw in logging code all over my webhook endpoint. Still nothing.
That’s when I realized—WordPress didn’t even see the request! It wasn’t routing it to my PHP handler at all. The request didn’t match any known WordPress route.
Why? Because WordPress has something called rewrite rules.
What are rewrite rules?
WordPress wants your site URLs to look nice. Instead of ugly ones like:
?p=123
You get pretty ones like:
/blog/my-post-name/
To make that magic happen, WordPress rewrites the URL behind the scenes using a set of rules. These rules tell WordPress how to interpret different path structures—and what PHP code should handle them.
But if a URL doesn’t match any known pattern, WordPress gets confused. It may throw a 404 error. Or worse—it may silently fail and not do anything.
Why WordPress blocked my webhook
My webhook used the path:
/webhook-handler/
That looked totally innocent. But WordPress didn’t know what to do with it. My site wasn’t set up to recognize that path in its rewrite rules. WordPress just dropped the request, or sent it somewhere useless.
Even though the file webhook-handler.php existed and I included it in my theme, WordPress’s internal routing engine never reached it.
The eureka moment: Rewrite exceptions!
The fix? I needed to tell WordPress to leave that path alone.
That’s where rewrite rule exceptions come in. By registering a custom endpoint, I could make WordPress recognize /webhook-handler/ as a valid route—and let me handle it my way.
Here’s the magic I added to my theme’s functions.php:
add_action('init', function() {
add_rewrite_rule('^webhook-handler/?$', 'index.php?webhook_handler=1', 'top');
});
add_filter('query_vars', function($vars) {
$vars[] = 'webhook_handler';
return $vars;
});
add_action('template_redirect', function() {
if (get_query_var('webhook_handler')) {
// Your custom webhook handler logic
include get_template_directory() . '/webhook-handler.php';
exit;
}
});
After I added this and refreshed my permalinks (more on that in a sec), everything started working perfectly. Webhooks reached the handler. Data flowed. My site updated in real time once again.
Don’t forget to flush!
When you add new rewrite rules, WordPress needs to refresh its list. Otherwise, it won’t recognize your new rule.
To do that easily:
- Go to your WordPress admin.
- Navigate to Settings » Permalinks.
- Just click Save Changes.
That’s it! WordPress will rebuild the rewrite rules with your new handler added.
Why not just use a plugin?
Good question. Some plugins let you register REST endpoints or bypass WordPress’s rewrite rules entirely.
But in my case, I wanted full control over the webhook logic. Also, I didn’t want to bring in another plugin just for a single URL. If you’re working solo or on a custom theme, handling this yourself is simple and lightweight.
Bonus tip: Use HTTPS and verify payloads
If you’re handling webhooks directly, make sure you:
- Use HTTPS for security.
- Validate incoming requests (check a shared secret, token, or signature).
- Log each payload (at least during testing).
The worst thing is thinking everything’s okay, only to realize your webhook handler was silently failing!
In summary
WordPress rewrite rules are great for SEO and structure. But they can be a pain when you need a custom endpoint, like for an ESP webhook.
If your webhook requests go into the void, chances are WordPress doesn’t know what to do with them. Add a rewrite exception, refresh permalinks, and you’re golden.
Now, my real-time email subscriber syncs work like a charm again—and all it took was a little friendly chat with WordPress’s URL brain.
Hope this helped! Sync on, friends.
