Developer Reference

This is the comprehensive developer reference for FCHub Memberships. It covers everything you need to extend, integrate with, or debug the plugin.

Action Hooks

The plugin fires these WordPress action hooks during the membership lifecycle. All hooks are prefixed with fchub_memberships/.

Extension Actions

Listening to Hooks

add_action('fchub_memberships/grant_created', function (int $userId, int $planId, array $context) {
    // Your custom logic when a membership is granted
    $sourceType = $context['source_type'] ?? 'manual';
    error_log("User {$userId} granted plan {$planId} via {$sourceType}");
}, 10, 3);

REST API

All endpoints are under the fchub-memberships/v1 namespace. Administrative requests from WordPress use cookie authentication, an X-WP-Nonce header, and the capability stated below.

External membership writes use a WordPress Application Password over HTTPS. The authenticated user needs manage_fchub_memberships (or manage_options), and every Application Password write requires an Idempotency-Key header. Reusing that key with the same request replays the stored result; reusing it for different input returns a conflict.

The dedicated FCHub access key is deliberately narrower: it authenticates only GET /check-access through the X-API-Key header. Query-string api_key credentials are not accepted. Settings, webhook operations, and general administration routes require manage_options; the membership mutation and reconciliation exceptions are called out explicitly below. The read-only key cannot call any admin route.

Unless a table or note says otherwise, every /admin route requires manage_options. A same-origin WordPress request uses the logged-in cookie and an X-WP-Nonce header. An external client may instead use WordPress Application Password Basic authentication over HTTPS, with a user that has the stated capability. General admin writes do not require Idempotency-Key; that header is required only for the membership and reconciliation operations identified below.

Read-only and frontend API

/check-access accepts either plan=<slug> or resource_type=<type>&resource_id=<id> (with optional provider=wordpress_core), and identifies the user by exactly one of user_id or email. A logged-in user may omit the identity for a self-check. External clients send X-API-Key; the secure default limit is 300 verified-key requests per 60 seconds. /my-access requires a logged-in WordPress user.

Dynamic Options

Reconciliation and provider recovery

External callers authenticate these routes with a WordPress Application Password over HTTPS. Cookie-authenticated WordPress requests use X-WP-Nonce. FluentCRM reconciliation defaults to dry_run=true; non-dry Application Password calls use the same durable idempotency and replay contract as membership writes. Provider repair requires an idempotency key for both authentication modes.

WP-CLI Commands

All commands are under the wp fchub-membership namespace.

wp fchub-membership list-grants --member=<id|email> [--status=<status>] [--plan=<slug>]

wp fchub-membership grant --member=<id|email> --plan=<slug>

wp fchub-membership revoke --member=<id|email> --plan=<slug> [--reason=<text>]

wp fchub-membership revoke-by-order --order=<id> [--reason=<text>]

wp fchub-membership check --member=<id|email> --plan=<slug>

wp fchub-membership backfill [--dry-run] [--limit=<n>]

wp fchub-membership expire-check

wp fchub-membership drip-process [--limit=<n>]

wp fchub-membership purge-expired [--days=<n>] [--dry-run]

wp fchub-membership debug --member=<id|email>

wp fchub-membership stats [--period=<period>] [--aggregate]

wp fchub-membership export-members [--plan=<slug>] [--status=<status>] [--format=<csv|json|table>]

Webhooks

Webhooks send durable membership events to external services as signed HTTP POST requests with JSON bodies. Delivery is at-least-once: receivers must deduplicate by the stable event ID and must not assume exactly-once delivery.

Configuration

In Memberships > Settings > Webhooks & API:

• Create up to ten named endpoints. Production destinations require HTTPS and must resolve only to public addresses.
• Generate an independent signing secret for each endpoint. It is shown once; later responses expose only whether it is configured.
• Send a one-shot test through the endpoint's real signing and network-safety path. The endpoint cannot activate until that test succeeds.
• Activate, pause, rotate, or delete each endpoint independently.
• Generate the read-only access key separately. It is also shown once, stored as a password hash, and never returned by settings reads.

Copy either credential before acknowledging its dialog. There is no “show it again” endpoint, because secrets are traditionally less useful when treated as decorative settings copy.

Events

Payload Format

{
  "id": "8f14b86a-b3ec-4fe5-a8f7-8a01b694bf15",
  "schema_version": "1.0",
  "event_type": "grant_created",
  "occurred_at": "2026-07-22T08:00:00+00:00",
  "site_url": "https://example.com",
  "data": {
    "user": {
      "id": 42,
      "email": "member@example.com",
      "display_name": "Jane Doe"
    },
    "plan": {
      "id": 1,
      "title": "Pro Membership",
      "slug": "pro"
    },
    "context": {
      "source_type": "order",
      "source_id": 156
    }
  }
}

Signature Verification

Every webhook includes these headers:

The signature contract is:

signature = HMAC-SHA256(request_body, webhook_secret)

Verify the signature on your receiving end:

$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_FCHUB_SIGNATURE'] ?? '';
$expected = hash_hmac('sha256', $payload, $your_shared_secret);

if (!hash_equals($expected, $signature)) {
    http_response_code(403);
    exit('Invalid signature');
}

$event = json_decode($payload, true, flags: JSON_THROW_ON_ERROR);
$delivery = $_SERVER['HTTP_X_FCHUB_DELIVERY'] ?? '';
$eventType = $_SERVER['HTTP_X_FCHUB_EVENT'] ?? '';
$timestamp = $_SERVER['HTTP_X_FCHUB_TIMESTAMP'] ?? '';

if (!hash_equals((string) $event['id'], $delivery)
    || !hash_equals((string) $event['event_type'], $eventType)
    || !hash_equals((string) $event['occurred_at'], $timestamp)
) {
    http_response_code(400);
    exit('Invalid webhook metadata');
}

Verify the HMAC against the untouched request bytes before decoding the JSON. Then verify delivery ID, event type, and timestamp against the envelope. Record the delivery ID durably before applying side effects, and return a 2xx response only after that record and the intended effect are safe to acknowledge.

Delivery

The plugin persists one immutable event and one delivery per unique destination before scheduling fchub_memberships_deliver_webhook. Action Scheduler is preferred; WP-Cron provides the scheduling fallback. Scheduled arguments contain only the delivery ID.

The worker re-reads the stored event and current secret, signs the exact stored body, and sends it through WordPress safe HTTP with a 15-second timeout and at most three redirects. Every transport error or non-2xx response is a failed attempt. Retry delays after the first attempt are 60, 300, 1800, 7200, 21600, 86400 seconds, for seven total attempts. Valid Retry-After values on HTTP 429 and 503 are honoured up to 86,400 seconds.

Successful deliveries are retained for 30 days and terminal failures for 90 days. Pending, processing, and retrying rows are not purged. Stored response bodies are bounded, and history never exposes the event body or signing secret.

Operations

The WordPress admin calls these routes with cookie authentication and an X-WP-Nonce header. Their permission check is always manage_options; the read-only key and manage_fchub_memberships capability do not grant access.

Send a production-path test from Memberships > Settings or via REST:

curl -X POST https://example.com/wp-json/fchub-memberships/v1/admin/webhooks/test \
  -H "Cookie: wordpress_logged_in_..." \
  -H "X-WP-Nonce: <nonce>"

Rotating one endpoint secret pauses that endpoint and requires a fresh successful test before reactivation. A terminal failed delivery may be retried after rotation and will be signed with the endpoint's current secret. Deleting an endpoint cancels its unfinished deliveries while preserving terminal history.

Adapter System

The adapter system provides a uniform interface for granting and revoking access across different content providers.

AccessAdapterInterface

interface AccessAdapterInterface
{
    public function supports(string $resourceType): bool;
    public function grant(int $userId, string $resourceType, string $resourceId, array $context = []): array;
    public function revoke(int $userId, string $resourceType, string $resourceId, array $context = []): array;
    public function check(int $userId, string $resourceType, string $resourceId): bool;
    public function getResourceLabel(string $resourceType, string $resourceId): string;
}

Built-in Adapters

Registering Custom Adapters

Adapters are resolved by provider string. You can register custom resource types through the fchub_memberships/resource_types action:

add_action('fchub_memberships/resource_types', function ($registry) {
    $registry->register('my_resource', [
        'label'     => 'My Custom Resource',
        'group'     => 'content',
        'provider'  => 'my_plugin',
        'searchable' => true,
    ]);
});

Database Tables

All tables are prefixed with {wp_prefix}fchub_membership_.

CSV Import

The import system supports multiple CSV formats through parser classes implementing CsvParserInterface.

Built-in Parsers

Import Flow

1. Upload — CSV file is uploaded and validated
2. Preview — The parser processes the CSV and returns a preview of what will be imported (users matched, plans matched, conflicts detected)
3. Execute — Grants are created for each valid row. Existing grants are updated if found

Custom Parsers

Implement CsvParserInterface and register your parser via a hook to support additional CSV formats from other membership plugins.

Cron Jobs

WP-Cron Events

Action Scheduler Hooks

Lifecycle cron handlers check for FLUENTCART_VERSION before using FluentCart. Webhook reconciliation and cleanup are scheduled only after schema 1.8.0 and the durable webhook tables pass their readiness checks.