Title: BlueFairy API Gateway
Author: bluefairydevelopment
Published: <strong>November 16, 2026</strong>
Last modified: November 16, 2026

---

Search plugins

![](https://ps.w.org/bluefairy-api-gateway/assets/banner-772x250.png?rev=3805955)

![](https://ps.w.org/bluefairy-api-gateway/assets/icon-256x256.png?rev=3805955)

# BlueFairy API Gateway

 By [bluefairydevelopment](https://profiles.wordpress.org/bluefairydevelopment/)

[Download](https://downloads.wordpress.org/plugin/bluefairy-api-gateway.1.0.4.zip)

 * [Details](https://wordpress.org/plugins/bluefairy-api-gateway/#description)
 * [Reviews](https://wordpress.org/plugins/bluefairy-api-gateway/#reviews)
 *  [Installation](https://wordpress.org/plugins/bluefairy-api-gateway/#installation)
 * [Development](https://wordpress.org/plugins/bluefairy-api-gateway/#developers)

 [Support](https://wordpress.org/support/plugin/bluefairy-api-gateway/)

## Description

BlueFairy API Gateway sits in front of the WordPress REST API and does three things,
each managed from one screen at **Settings  API Gateway**.

**Response cache.** Anonymous `GET` responses are stored and served back with an`
X-BF-Cache: HIT` header; every REST response is labelled `HIT`, `MISS` or `BYPASS`
so you can see the decision from `curl`. Requests from logged-in users, or carrying
an `Authorization`, `X-WP-Nonce` or `X-BF-API-Key` header, are never cached. Responses
that are not 2xx, that stream, that set a cookie or whose `Cache-Control` says `
no-store`, `private`, `no-cache` or `max-age=0` are never stored. Up to 500 cache
rules, each matched by route glob (`wp/v2/posts/**` — a trailing `/**` or `/*` matches
the collection route too) with its own lifetime; the most specific matching rule
wins, and one is seeded on activation as “all routes, 60 seconds”. The cache is 
purged automatically when a post, term or comment changes, and by hand from the 
Cache tab or `POST /bfag/v1/cache/purge`. Responses live in your persistent object
cache (Redis, Memcached) when you have one, otherwise in transients — capped there
at 64 KB per response and one hour, and swept every five minutes.

**Rate limiting.** A sliding-window counter per client IP and rule (an IPv6 client
is counted by its /64 network, so rotating addresses within it does not escape the
limit). The breaching request gets `429 Too Many Requests` with `Retry-After`, `
X-BF-RateLimit-Limit` and `X-BF-RateLimit-Window`. Up to 500 rules, each counting
the routes its glob matches; one is seeded as 300 requests per 60 seconds across
every route, and logged-in users who can edit posts are exempt by default in their
own browser session (requests made with an API key or an application password are
always limited). One forwarded-IP header of your choosing (`X-Forwarded-For` by 
default; `CF-Connecting-IP`, `X-Real-IP` or `True-Client-IP`) is honoured, and only
from the proxy ranges you list, so a visitor cannot pick their own bucket. A client
over the limit is refused from a marker for the rest of its window without touching
the database; with a persistent object cache the count itself is an atomic increment
rather than a query. The hit log is pruned every five minutes.

**Signed outbound webhooks.** Up to 500 webhooks, each subscribing to one event:
post published, updated or deleted; user registered or updated; comment created;
and, with WooCommerce, order created, order status changed, order completed, product
updated. Each delivery is a JSON `POST` carrying `X-BF-Event`, `X-BF-Delivery`, `
X-BF-Timestamp` and `X-BF-Signature: sha256=HMAC-SHA256(timestamp.body, secret)`,
so the receiver can verify both origin and freshness. Deliveries are collected during
the request and sent once after the response — twenty at most, and for fifteen seconds
at most, the rest through a WP-Cron event so a bulk import or a dead endpoint never
ties up the request that saved it — logged with their HTTP status and response body,
and any failed delivery can be resent from the log. Targets must be `https://`; 
a secret is generated for you and shown once, right after saving, for you to copy
into the receiver.

**Dashboard.** Cache hit rate and webhook success rate over the last 24 hours, the
current size of the rate-limit log, the ten most recent failed deliveries with a
Retry button, and the same figures at `GET /bfag/v1/status` for a monitoring tool—
a route that is never rate-limited.

**Add API Gateway Pro** for purges narrowed to the tags a change touches; rate limits
per user and per API key with penalty blocks; DDoS auto-block with a blocked-IPs
panel; automatic webhook retries with back-off and failure alerts by email; Salesforce,
HubSpot and Mailchimp presets; a verified incoming-webhook endpoint (HubSpot signed;
Salesforce and Mailchimp shared secret); a webhook REST API; API keys with scopes;
and WPGraphQL query caching. Pro installs alongside this plugin rather than replacing
it.

### Admin Instructions

Everything lives under **Settings  API Gateway**, in five tabs.

**Dashboard** — three cards (cache hit rate, webhook success rate for outgoing deliveries,
and the Pro _Active blocks_ count — shown as _Blocked (Pro)_ without the add-on)
recomputed every five minutes or when you press **Refresh**; the ten newest failed
deliveries with **Retry**; the raw counts; and the status endpoint URL with a **
Copy** button. Timestamps are shown in the site’s timezone.

**Cache** — the rules table with an Enabled/Disabled badge you can click, **Edit**
and **Delete**, and **Purge all**. The add/edit form takes a label, a route glob(
matched without the leading slash: `wc/v3/products/*` matches `wc/v3/products` and`
wc/v3/products/12`), a TTL in seconds and optional comma-separated tags. Every content
change purges every rule; with API Gateway Pro a tagged rule is purged only by the
changes that touch its tags. Edit the seeded “All routes” rule to narrow it. With
more than one rule the most specific one wins, and the table is listed in that order.

**Rate limit** — the rules table and a form with a label, _Count by_ (IP address),
a route glob, and the limit: how many requests are allowed in how many seconds. 
Values outside 1–65535 requests or 1–86400 seconds are refused rather than silently
changed.

**Webhooks** — the webhooks table with **Edit**, **Send test** and **Delete**, the**
Delivery log** button, and the add/edit form: label, `https://` URL, event, signing
secret (blank generates one and shows it once after saving), extra headers as `Name:
value` lines, and an Enabled box. Press **Send test** on a new webhook: the notice
reports the HTTP status, and the delivery log shows the receiver’s response under
each row.

**Settings** — the cache switch and _New-rule TTL_; the rate-limiting switch, _Exempt
editors_, _Trusted proxies_ and _Client address header_; the stored-payload cap 
and delivery-log retention; debug logging, the WP-Cron notice switch and _Delete
data on uninstall_. The notification email and failure threshold appear only with
the Pro add-on, which is what sends the alerts.

To confirm the cache from the command line, request a public route twice and read
the header: `curl -sI https://example.com/wp-json/wp/v2/posts | grep -i x-bf-cache`—`
MISS` then `HIT`.

### External services

This plugin connects to services outside your site in one way only: **outbound webhooks
that you configure**. Nothing is sent anywhere until an administrator adds a webhook
on **Settings  API Gateway  Webhooks**, and the plugin never contacts Blue Fairy
Development or any other fixed address — there is no telemetry, licence check or
update server.

 * **What it is used for:** notifying another system (your own app, an automation
   service, a CRM relay — whatever endpoint you choose) that something happened 
   on your site.
 * **Where data is sent:** only to the `https://` URL you enter for each webhook,
   and only for the one event that webhook subscribes to. **Send test** sends a 
   sample `test` event to that URL when you press it.
 * **What is sent, and when:** a JSON `POST` each time the subscribed event happens,
   carrying the event name, your site URL, a timestamp and the object’s allow-listed
   fields — for a post: id, type, status, title, slug, link, author id and dates;
   for a user: id, login, email, display name and roles; for a comment: id, post
   id, author name, author email, approval status, date and type; for a WooCommerce
   order: id, status, currency, total, customer id, billing email and date created;
   for a product: id, name, SKU, status, price and type. Each request also carries
   the `X-BF-Event`, `X-BF-Delivery`, `X-BF-Timestamp` and `X-BF-Signature` headers
   and any extra headers you added to the webhook.
 * **Whose terms apply:** the receiving service is one you choose and control, so
   its terms of service and privacy policy are the ones that govern the data. Review
   them before sending personal data such as email addresses to it, and mention 
   the transfer in your own site’s privacy policy where the law requires.

## Screenshots

[⌊Dashboard — cache hit rate and webhook success rate over 24 hours, the recent 
failed deliveries with Retry, the row counts and the status endpoint.⌉⌊Dashboard—
cache hit rate and webhook success rate over 24 hours, the recent failed deliveries
with Retry, the row counts and the status endpoint.⌉[

Dashboard — cache hit rate and webhook success rate over 24 hours, the recent failed
deliveries with Retry, the row counts and the status endpoint.

[⌊Cache — the seeded "All routes" rule (1 of 500) with its route glob, TTL and Enabled
badge, Purge all, and the form to add another rule.⌉⌊Cache — the seeded "All routes"
rule (1 of 500) with its route glob, TTL and Enabled badge, Purge all, and the form
to add another rule.⌉[

Cache — the seeded “All routes” rule (1 of 500) with its route glob, TTL and Enabled
badge, Purge all, and the form to add another rule.

[⌊Rate limit — the seeded per-IP rule: 300 requests per 60 seconds on every route.⌉⌊
Rate limit — the seeded per-IP rule: 300 requests per 60 seconds on every route.⌉[

Rate limit — the seeded per-IP rule: 300 requests per 60 seconds on every route.

[⌊Webhooks — three signed webhooks with their events and last-delivery status, Send
test, and the Delivery log button.⌉⌊Webhooks — three signed webhooks with their 
events and last-delivery status, Send test, and the Delivery log button.⌉[

Webhooks — three signed webhooks with their events and last-delivery status, Send
test, and the Delivery log button.

[⌊Settings — the cache, rate-limit, webhooks and advanced groups.⌉⌊Settings — the
cache, rate-limit, webhooks and advanced groups.⌉[

Settings — the cache, rate-limit, webhooks and advanced groups.

[⌊Delivery log — every delivery with its HTTP status; a failed delivery's response
opened, with Retry.⌉⌊Delivery log — every delivery with its HTTP status; a failed
delivery's response opened, with Retry.⌉[

Delivery log — every delivery with its HTTP status; a failed delivery’s response
opened, with Retry.

## Installation

 1. Upload the `bluefairy-api-gateway` folder to `/wp-content/plugins/`, or install
    the zip from **Plugins  Add New  Upload Plugin**.
 2. Activate the plugin from the **Plugins** screen. PHP 8.1 or newer is required; 
    activation refuses otherwise.
 3. Open **Settings  API Gateway**.

Activation creates six database tables, seeds one cache rule and one rate-limit 
rule, grants the `bfag_manage_gateway` capability to administrators and schedules
four recurring WP-Cron jobs. The cache and the rate limiter are on from the first
request; nothing is sent anywhere until you add a webhook.

## FAQ

### Why am I seeing X-BF-Cache: BYPASS?

BYPASS means the request or the response was not cacheable. On the request side:
the cache is switched off; the method is not GET or HEAD; you are logged in (a browser
with a WordPress cookie, including the admin’s own browser); the request carries
an `Authorization`, `X-WP-Nonce` or `X-BF-API-Key` header; the route is under `/
bfag/v1`; or no enabled cache rule matches the route. On the response side: the 
status is not 2xx; the response streams (`text/event-stream`); it sets a cookie (
including through PHP’s `setcookie()`, as WooCommerce’s guest cart session does —
a plugin that sets a cookie on every request keeps responses from being stored);
or its `Cache-Control` says `no-store`, `private`, `no-cache` or `max-age=0`. Test
with `curl` from a fresh shell, not from a logged-in browser tab.

### Does it work without Redis or Memcached?

Yes. With a persistent object cache responses are stored in the object-cache group`
bfag_responses`; without one they are stored as transients in the options table —
capped at 64 KB per response and one hour, with expired entries swept every five
minutes — and purging works the same way on both. A persistent object cache is faster,
has no size cap, keeps the options table small and turns the rate-limit count and
the cache statistics into in-memory increments, so use one on a busy site.

### What happens behind Cloudflare, a load balancer or a reverse proxy?

By default the client IP is `REMOTE_ADDR`, which behind a proxy is the proxy’s own
address — so every visitor would share one rate-limit bucket. List the proxy’s addresses
or CIDR ranges under **Settings  Rate limit  Trusted proxies** (for Cloudflare, 
its published IP ranges) and pick the **Client address header** your proxy writes(`
X-Forwarded-For` by default; for Cloudflare, `CF-Connecting-IP`). Only when `REMOTE_ADDR`
is inside one of those ranges is that one header read — for `X-Forwarded-For`, taking
the right-most address that is not itself a trusted proxy. Every other header, and
headers from anywhere else, are ignored, so a visitor cannot forge their way into
a different bucket, not even by adding an `X-Real-IP` of their own in front of a
proxy that only manages `X-Forwarded-For`.

### Does uninstalling delete my data?

Deleting the plugin always removes its options, transients, cron events and the `
bfag_manage_gateway` capability. Your rules, webhooks and delivery log — the six`
bfag_` database tables — are dropped only if you ticked **Delete data on uninstall**
under Settings  Advanced first. By default they stay, because a delivery log is 
a record of what was sent, not a cache. Deactivating removes only the cron events
and the capability.

### How do retries work?

In the free plugin a failed delivery — any non-2xx answer, or no answer within five
seconds — is marked `failed` in the log and stays there. Press **Retry** — offered
on failed deliveries only — on the dashboard or in the delivery log to resend the
stored payload bytes as the next attempt, with a fresh timestamp and signature and
the same `X-BF-Delivery` id. A delivery whose stored payload was truncated at the
_Max stored payload_ setting cannot be retried, because the stored bytes are no 
longer what was signed. Automatic retries with back-off (one minute, five minutes,
thirty minutes, up to a per-webhook limit) and failure alerts are part of API Gateway
Pro.

### How does my receiver verify the signature?

Compute `HMAC-SHA256` with the webhook’s secret over the string `X-BF-Timestamp 
+ "." + raw request body`, hex-encode it, prefix `sha256=`, and compare it to `X-
BF-Signature` in constant time (`hash_equals()` in PHP, `crypto.timingSafeEqual()`
in Node). Read the raw body bytes before any framework parses them. Reject timestamps
more than a few minutes old to defeat replay. Full PHP and Node examples are in 
the features guide shipped with the plugin, `docs/ApiGatewayFeaturesGuide.pdf`, 
under _Webhooks  Verifying at the receiver_.

### Why does editing a blog post empty the whole cache?

Because the free plugin has no way to tell which cached responses a change touches,
so any post, term or comment change flushes everything. API Gateway Pro answers 
the `bfag_cache_purge_tags` filter with the tags each change touches (`post:42`,`
type:product`, `term:7`, `tax:category`, `all`), so a rule tagged `type:product`
survives a blog post edit. A rule with no tags is purged on every content change
even with Pro; add tags to narrow purging to those tags.

### Will my logged-in users or my app’s authenticated API calls be cached?

No. A request with a WordPress login cookie, an `Authorization` header (Application
Passwords, bearer tokens), an `X-WP-Nonce` or an `X-BF-API-Key` is never served 
from or stored in the cache, because such a response may contain data nobody else
should see. Only anonymous public reads are cached.

### How many rules and webhooks can I add?

Up to 500 cache rules, 500 rate-limit rules and 500 webhooks — the same with or 
without API Gateway Pro. The ceiling keeps the admin lists and the rule matching
on every request quick; a developer can lower it, or raise it to at most 1,000, 
with the `bfag_cache_rule_limit`, `bfag_rate_limit_rule_limit` and `bfag_webhook_limit`
filters. When every one is in use the add form gives way to a line saying so: edit
or delete one to add another. Rate limiting counts by IP address; Pro adds per-user
and per-API-key counting.

### The webhook will not save — “URL refused: it must start with https:// and resolve to a public address”.

Each refused field has its own notice: _URL refused…_ for the URL, _Webhook not 
saved: the label must be 1–200 characters_ for the label, _Webhook not saved: choose
an event from the list_ for the event, and _Webhook not saved: check the extra headers(
one Name: value per line) and the secret (255 characters at most)_ for the rest.
Your entries are kept in the form.

The URL must start with `https://` and must pass WordPress’s own `wp_http_validate_url()`
check, which refuses loopback and private addresses such as `localhost`, `127.0.0.1`
or `10.x.x.x`. For local development a developer can allow `http://` with the `bfag_webhook_allow_http`
filter. The event must be one offered in the dropdown — a WooCommerce event disappears
from the list when WooCommerce is deactivated.

### I let the plugin generate the signing secret and did not copy it. Where is it?

A generated secret is shown exactly once, on the Webhooks tab right after you save,
with a **Copy** button; after that the stored secret cannot be read back from the
admin page. If you missed it, edit the webhook and either type your own secret into
the field, or tick **Generate a new secret** and save — the new one is shown once
in the same way. Either way, update the receiver: deliveries fail there until it
has the new secret.

### Does it need WP-Cron?

The hit-log prune, the delivery-log prune and the dashboard figures run on WP-Cron.
The first 20 webhook deliveries of a request are sent at the end of that request;
the rest are queued and sent by `bfag_cron_flush_pending`, a single event scheduled
on demand. If `DISABLE_WP_CRON` is set the plugin shows a notice on its own screen;
make sure a system cron runs `wp-cron.php`, then tick **Hide the WP-Cron notice**.
There are no WP-CLI commands; `wp cron event run bfag_cron_prune_hits` runs a job
on demand.

### Does it work with WooCommerce?

Yes. While WooCommerce is active four more events are offered: order created, order
status changed, order completed and product updated, each carrying the order or 
product fields (id, status, currency, total, customer id, billing email; id, name,
SKU, status, price, type). WooCommerce’s own REST routes under `wc/v3/…` can be 
cached and rate-limited like any other, subject to the same rule that authenticated
requests are never cached.

### Does it support multisite?

Network activation provisions every site — tables, the seeded rules, the capability
and the cron jobs — and a site added later is provisioned when it is created. Each
site keeps its own rules, webhooks and settings. Uninstalling cleans up on every
site of the network.

## Reviews

There are no reviews for this plugin.

## Contributors & Developers

“BlueFairy API Gateway” is open source software. The following people have contributed
to this plugin.

Contributors

 *   [ bluefairydevelopment ](https://profiles.wordpress.org/bluefairydevelopment/)

[Translate “BlueFairy API Gateway” into your language.](https://translate.wordpress.org/projects/wp-plugins/bluefairy-api-gateway)

### Interested in development?

[Browse the code](https://plugins.trac.wordpress.org/browser/bluefairy-api-gateway/),
check out the [SVN repository](https://plugins.svn.wordpress.org/bluefairy-api-gateway/),
or subscribe to the [development log](https://plugins.trac.wordpress.org/log/bluefairy-api-gateway/)
by [RSS](https://plugins.trac.wordpress.org/log/bluefairy-api-gateway/?limit=100&mode=stop_on_copy&format=rss).

## Changelog

#### 1.0.4

 * Security: a request authenticated by an API key or application password is now
   always rate-limited and can be blocked, whoever the key belongs to. “Exempt editors”
   now covers only an editor’s own browser session. New filter `bfag_rate_limit_exempt`.
 * Change: rate-limit rules count an IPv6 client by its /64 network, so rotating
   addresses within one /64 no longer escapes a limit. Devices sharing one IPv6 /
   64 now share one budget.

#### 1.0.3

 * Readme: the rate-limit form description is reworded. No code change.

#### 1.0.2

 * Fix: the first page load after an update could book the scheduled jobs during
   plugin loading, before WordPress’s `init`. With WooCommerce (or another plugin
   that translates its cron schedule names) active, WordPress logged “Translation
   loading for the woocommerce domain was triggered too early”. The jobs are now
   booked at `init`, on that same page load.
 * Fix: a scheduled job lost to a cron wipe or a restore (hit-log, delivery-log 
   and cached-response pruning, the dashboard figures) is booked again on the next
   page load. Before, it stayed lost until the plugin was re-activated and those
   logs were never pruned.

#### 1.0.1

 * Up to 500 cache rules, 500 rate-limit rules and 500 webhooks — was one, one and
   three. The ceiling is now the same with or without API Gateway Pro, which is 
   sold on its own features alone. The page shown when every one is in use, and 
   the notice when a save is refused for that reason, no longer mention Pro.
 * The Pro panel lists only what Pro adds, with no limit among them.
 * Packaging for WordPress.org; no change to settings or data.
 * The readme gains an _External services_ section describing the outbound webhooks
   you configure.
 * The Markdown feature reference is no longer in the plugin zip; everything it 
   held — including the receiver signature examples and the Pro comparison — is 
   in the features guide, `docs/ApiGatewayFeaturesGuide.pdf`.
 * The time-limit lift used while a network-wide activation provisions every site
   is documented in the code.
 * Screenshots retaken on this version; a sixth shows the delivery log. The features
   guide is rebuilt with the new dashboard and delivery-log images.

#### 1.0.0

 * First release.
 * REST response cache with `X-BF-Cache: HIT` / `MISS` / `BYPASS`, one route-glob
   rule, object-cache or transient storage (64 KB / one-hour cap on transients),
   generation-based purging on post, term and comment changes, Purge all, and `POST/
   bfag/v1/cache/purge`.
 * Sliding-window rate limiting per IP and rule with `429`, `Retry-After` and `X-
   BF-RateLimit-*` headers; one rule seeded at 300 per 60 s; editors exempt by default
   in a browser session (never API-key traffic); trusted-proxy IP resolution from
   one chosen header; refused requests served from a marker with no database work.
 * Up to three signed outbound webhooks on six WordPress events and four WooCommerce
   events, HMAC-SHA256 `X-BF-Signature` over `timestamp.body`, delivery after the
   response (twenty at most, fifteen seconds at most, the rest by WP-Cron), a delivery
   log with Send test and Retry on failed outgoing deliveries, payload truncation
   and retention pruning.
 * Dashboard figures recomputed every five minutes, `GET /bfag/v1/status` for monitors,
   the `bfag_manage_gateway` capability, multisite provisioning.
 * Thirty-six `bfag_*` actions and filters as the add-on contract.
 * Compatibility: tested against WordPress 7.1; requires PHP 8.1 or newer. Database
   schema version 1.0.3 (internal).

## Meta

 *  Version **1.0.4**
 *  Last updated **5 hours ago**
 *  Active installations **Fewer than 10**
 *  WordPress version ** 6.6 or higher **
 *  Tested up to **7.1.4**
 *  PHP version ** 8.1 or higher **
 * Tags
 * [cache](https://wordpress.org/plugins/tags/cache/)[headless](https://wordpress.org/plugins/tags/headless/)
   [rate limit](https://wordpress.org/plugins/tags/rate-limit/)[rest-api](https://wordpress.org/plugins/tags/rest-api/)
   [webhooks](https://wordpress.org/plugins/tags/webhooks/)
 *  [Advanced View](https://wordpress.org/plugins/bluefairy-api-gateway/advanced/)

## Ratings

No reviews have been submitted yet.

[Your review](https://wordpress.org/support/plugin/bluefairy-api-gateway/reviews/#new-post)

[See all reviews](https://wordpress.org/support/plugin/bluefairy-api-gateway/reviews/)

## Contributors

 *   [ bluefairydevelopment ](https://profiles.wordpress.org/bluefairydevelopment/)

## Support

Got something to say? Need help?

 [View support forum](https://wordpress.org/support/plugin/bluefairy-api-gateway/)

## Donate

Would you like to support the advancement of this plugin?

 [ Donate to this plugin ](https://ko-fi.com/bluefairydevelopment)