---
title: Action Hooks
slug: action-hooks
type: reference
plugin: huxx-connect
summary: Every action HuxxConnect and HuxxConnect Pro fire, grouped by area, for reacting to requests, cache events, config changes, sync runs, and token events. Pro hooks are marked.
keywords: [hooks, actions, reference, extensibility]
version_added: 1.2.5
version_updated: 1.2.5
level: advanced
---

New to hooks? Most customizations never need them — start with the [how-to guides](/docs/connect/how-to/use-template-functions/). This page is the complete action reference, grouped by area; every entry links to its source and shows its signature.

## Requests

### huxx_connect/request/after

Action after the request is completed (cache hit).

**Type:** action · **Since:** — · **Source:** `src/Core/Executor.php`

```php
do_action( 'huxx_connect/request/after', $cached, $request, $api, $endpoint, $source );
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `$cached` | `mixed` | The cached response data. |
| `$request` | `array` | The built request (url + args). |
| `$api` | `Api` | The API being called. |
| `$endpoint` | `Endpoint` | The endpoint being called. |
| `$source` | `string` | The result source: 'cache_hit'. |

<!-- example:huxx_connect/request/after -->
```php
add_action( 'huxx_connect/request/after', function ( $result, array $request, $api, $endpoint, string $source ) {
    if ( 'stale_cache' === $source ) {
        error_log( 'Served stale cache for ' . $request['url'] . ' — the API may be down.' );
    }
}, 10, 5 );
```

Log output when the remote API fails and the stale-cache fallback serves the last good response:

```
Served stale cache for https://dummyjson.com/products — the API may be down.
```

### Notes

- Unlike [`huxx_connect/request/before`](/docs/connect/reference/action-hooks/#huxx-connect-request-before), this fires for **every** outcome, making it the right hook for logging and monitoring.
- `stale_cache` means the live request failed and the last good response was served within its stale-cache fallback window.
<!-- /example:huxx_connect/request/after -->

### huxx_connect/request/before

Action before the HTTP request is sent.

**Type:** action · **Since:** — · **Source:** `src/Core/Executor.php`

```php
do_action( 'huxx_connect/request/before' );
```

<!-- example:huxx_connect/request/before -->
```php
add_action( 'huxx_connect/request/before', function ( array $request, $api, $endpoint ) {
    error_log( sprintf( 'HuxxConnect calling %s (%s)', $request['url'], $api->get_id() ) );
}, 10, 3 );
```

Output in the PHP error log:

```
HuxxConnect calling https://dummyjson.com/products (dummyjson)
```

### Notes

- Fires for every trigger source: shortcode, template function, admin test panel, and Pro syncs.
- Does **not** fire on cache hits — a cached response returns before the HTTP request is built. Use `huxx_connect/request/after` (which fires with source `cache_hit` or `http`) to observe every request outcome.
- This is an observation hook. To *modify* the outgoing request, use the `huxx_connect/request/args` filter instead.
<!-- /example:huxx_connect/request/before -->

## Caching

### huxx_connect/cache/flush_api

Fires before flushing cache for an API.

**Type:** action · **Since:** — · **Source:** `src/Cache/CacheManager.php`

```php
do_action( 'huxx_connect/cache/flush_api', $api_id );
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `$api_id` | `string` | API identifier. |

<!-- example:huxx_connect/cache/flush_api -->
Fires just before every cached response for an API is dropped. Use it to observe or to invalidate your own companion caches.

```php
add_action( 'huxx_connect/cache/flush_api', function ( $api_id ) {
	error_log( "HuxxConnect: flushing all cached responses for API {$api_id}" );
} );
```

Result (error log): `HuxxConnect: flushing all cached responses for API demo_api`
<!-- /example:huxx_connect/cache/flush_api -->

### huxx_connect/cache/flush_endpoint

Fires before flushing cache for an endpoint.

**Type:** action · **Since:** — · **Source:** `src/Cache/CacheManager.php`

```php
do_action( 'huxx_connect/cache/flush_endpoint', $api_id, $endpoint_id );
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `$api_id` | `string` | API identifier. |
| `$endpoint_id` | `string` | Endpoint identifier. |

<!-- example:huxx_connect/cache/flush_endpoint -->
Fires before a single endpoint's cached responses are dropped. Handy for clearing a companion transient you built from that endpoint's data.

```php
add_action( 'huxx_connect/cache/flush_endpoint', function ( $api_id, $endpoint_id ) {
	// Also drop a companion page transient keyed to this endpoint.
	if ( $api_id === 'demo_api' && $endpoint_id === 'get_products' ) {
		delete_transient( 'my_products_grid_html' );
	}
}, 10, 2 );
```

Result: flushing the `demo_api` / `get_products` cache also clears your `my_products_grid_html` transient so the rendered grid rebuilds.
<!-- /example:huxx_connect/cache/flush_endpoint -->

### huxx_connect/cache/hit

Cache hit event.

**Type:** action · **Since:** — · **Source:** `src/Cache/CacheManager.php`

```php
do_action( 'huxx_connect/cache/hit', $api_id, $endpoint_id, $key );
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `$api_id` | `string` | API identifier. |
| `$endpoint_id` | `string` | Endpoint identifier. |
| `$key` | `string` | Cache key. |

<!-- example:huxx_connect/cache/hit -->
Observation-only event fired whenever a fresh cached response is served (no HTTP request made). It cannot change the response — use it for metrics.

```php
add_action( 'huxx_connect/cache/hit', function ( $api_id, $endpoint_id, $key ) {
	$count = (int) get_transient( 'huxx_cache_hits' );
	set_transient( 'huxx_cache_hits', $count + 1, DAY_IN_SECONDS );
}, 10, 3 );
```

Result: a rolling daily counter in the `huxx_cache_hits` transient increments on every cache hit.
<!-- /example:huxx_connect/cache/hit -->

### huxx_connect/cache/miss

Cache miss event.

**Type:** action · **Since:** — · **Source:** `src/Cache/CacheManager.php`

```php
do_action( 'huxx_connect/cache/miss' );
```

<!-- example:huxx_connect/cache/miss -->
Observation-only event fired when no fresh cache entry exists, just before the live HTTP request runs. It cannot prevent the request — use it for logging.

```php
add_action( 'huxx_connect/cache/miss', function ( $api_id, $endpoint_id, $key ) {
	error_log( "HuxxConnect cache MISS: {$api_id}/{$endpoint_id}" );
}, 10, 3 );
```

Result (error log): `HuxxConnect cache MISS: demo_api/get_products`
<!-- /example:huxx_connect/cache/miss -->

### huxx_connect/cache/stale_fallback

Fires when stale cached data is served as a fallback.

**Type:** action · **Since:** — · **Source:** `src/Core/Executor.php`

```php
do_action( 'huxx_connect/cache/stale_fallback', $stale_data, $error, $api, $endpoint );
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `$stale_data` | `mixed` | The stale cached response data. |
| `$error` | `ErrorResponse` | The original error that triggered the fallback. |
| `$api` | `Api` | The API being called. |
| `$endpoint` | `Endpoint` | The endpoint being called. |

<!-- example:huxx_connect/cache/stale_fallback -->
Fires when a live request errors and HuxxConnect serves an older stale copy instead. Observation-only — the stale data is already being returned. Use it to alert or log.

```php
add_action( 'huxx_connect/cache/stale_fallback', function ( $stale_data, $error, $api, $endpoint ) {
	error_log( sprintf(
		'HuxxConnect served STALE cache for %s/%s after API error: %s',
		$api->get_id(),
		$endpoint->get_id(),
		$error->get_message()
	) );
}, 10, 4 );
```

Result (error log): `HuxxConnect served STALE cache for demo_api/get_products after API error: Connection timed out`
<!-- /example:huxx_connect/cache/stale_fallback -->

### huxx_connect/cache/stale_hit

Stale cache hit event.

**Type:** action · **Since:** — · **Source:** `src/Cache/CacheManager.php`

```php
do_action( 'huxx_connect/cache/stale_hit', $api_id, $endpoint_id, $key );
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `$api_id` | `string` | API identifier. |
| `$endpoint_id` | `string` | Endpoint identifier. |
| `$key` | `string` | Cache key. |

<!-- example:huxx_connect/cache/stale_hit -->
Observation-only event fired when a stale-fallback copy is found and served. It cannot change the response — use it for logging.

```php
add_action( 'huxx_connect/cache/stale_hit', function ( $api_id, $endpoint_id, $key ) {
	error_log( "HuxxConnect stale cache HIT: {$api_id}/{$endpoint_id}" );
}, 10, 3 );
```

Result (error log): `HuxxConnect stale cache HIT: demo_api/get_products`
<!-- /example:huxx_connect/cache/stale_hit -->

## Import & Export

### huxx_connect/import/complete

Fires after an import has completed successfully.

**Type:** action · **Since:** — · **Source:** `src/ImportExport/Importer.php`

```php
do_action( 'huxx_connect/import/complete', $stats, $mode, $data );
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `$stats` | `array` | The import statistics (apis_created, endpoints_created, etc.). |
| `$mode` | `string` | The import mode ('merge' or 'overwrite'). |
| `$data` | `array` | The raw import data. |

<!-- example:huxx_connect/import/complete -->
Write a log line each time a configuration import finishes:

```php
add_action( 'huxx_connect/import/complete', function ( $stats, $mode, $data ) {
    error_log( sprintf(
        'HuxxConnect import (%s): %d APIs, %d endpoints created.',
        $mode,
        $stats['apis_created'] ?? 0,
        $stats['endpoints_created'] ?? 0
    ) );
}, 10, 3 );
```

Result (in `debug.log`):

```
HuxxConnect import (merge): 1 APIs, 1 endpoints created.
```
<!-- /example:huxx_connect/import/complete -->

### huxx_connect/migration/wpgetapi/after_import

Fires after a successful WPGetAPI migration. Lets companion plugins (notably HuxxConnect Pro's Post Creator) migrate sibling configs (e.g. WPGetAPI API-to-Posts importer settings) in the same flow.

**Type:** action · **Since:** 1.1.2 · **Source:** `src/Admin/Rest/ImportExportController.php`

```php
do_action( 'huxx_connect/migration/wpgetapi/after_import', $import_result, $migrator_data );
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `$import_result` | `array` | Free migrator's import_result {success, message, stats}, passed by reference. |
| `$migrator_data` | `array` | Raw extracted data from WpGetApiMigrator::extract() — has 'apis' (each with 'endpoints'), letting subscribers correlate api_id/endpoint_id without re-reading wp_options. |

<!-- example:huxx_connect/migration/wpgetapi/after_import -->
Migrate a sibling plugin's settings in the same WPGetAPI migration flow. `$import_result` is passed by reference so you can append your own count to the migration toast via `stats.extra[]` (do not flip the top-level `success` flag):

```php
add_action( 'huxx_connect/migration/wpgetapi/after_import', function ( &$import_result, $migrator_data ) {
    $migrated = 0;
    foreach ( $migrator_data['apis'] ?? array() as $api ) {
        // ...port each $api['api_id'] sibling config here.
        $migrated++;
    }

    $import_result['stats']['extra'][] = array(
        'label' => 'Sibling configs migrated',
        'count' => $migrated,
    );
}, 10, 2 );
```

Result: the combined migration toast reports your `Sibling configs migrated` count next to the free plugin's own totals.
<!-- /example:huxx_connect/migration/wpgetapi/after_import -->

## Lifecycle & Data Events

### huxx_connect/admin/api_deleted

Fires after an API has been deleted. Fires on any persistence (admin save, import, migration, or programmatic write), not only from the admin screen.

**Type:** action · **Since:** — · **Source:** `src/Storage/ApiRepository.php`

```php
do_action( 'huxx_connect/admin/api_deleted', $api_id );
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `$api_id` | `string` | The API slug that was deleted. |

<!-- example:huxx_connect/admin/api_deleted -->
Clean up companion data your own plugin stored alongside a HuxxConnect API when that API is removed.

```php
add_action( 'huxx_connect/admin/api_deleted', function ( $api_id ) {
	// Drop a transient your integration keyed by the API id.
	delete_transient( 'my_plugin_menu_' . $api_id );
	error_log( '[HuxxConnect] API deleted, cleared companion cache: ' . $api_id );
}, 10, 1 );
```

Result (after deleting `demo_api`):

```
[HuxxConnect] API deleted, cleared companion cache: demo_api
```
<!-- /example:huxx_connect/admin/api_deleted -->

### huxx_connect/admin/api_saved

Fires after an API configuration is created or updated. Fires on any persistence (admin save, import, migration, or programmatic write), not only from the admin screen.

**Type:** action · **Since:** — · **Source:** `src/Storage/ApiRepository.php`

```php
do_action( 'huxx_connect/admin/api_saved', $api_id, $data );
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `$api_id` | `int|string` | The API database ID (on create) or slug (on update). |
| `$data` | `array` | The API data. |

<!-- example:huxx_connect/admin/api_saved -->
Log every API create/update to keep an external audit trail. Fires on any persistence, so admin saves, imports, and migrations are all covered.

```php
add_action( 'huxx_connect/admin/api_saved', function ( $api_id, $data ) {
	error_log( sprintf(
		'[HuxxConnect] API "%s" saved (base URL: %s)',
		$api_id,
		$data['base_url'] ?? 'n/a'
	) );
}, 10, 2 );
```

Result (in `debug.log` after saving the `demo_api` config):

```
[HuxxConnect] API "demo_api" saved (base URL: https://dummyjson.com)
```
<!-- /example:huxx_connect/admin/api_saved -->

### huxx_connect/admin/endpoint_deleted

Fires after an endpoint has been deleted. Fires on any persistence (admin save, import, migration, or programmatic write), not only from the admin screen.

**Type:** action · **Since:** — · **Source:** `src/Storage/EndpointRepository.php`

```php
do_action( 'huxx_connect/admin/endpoint_deleted', $api_id, $endpoint_id );
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `$api_id` | `string` | The API slug. |
| `$endpoint_id` | `string` | The endpoint slug that was deleted. |

<!-- example:huxx_connect/admin/endpoint_deleted -->
Both the parent API id and the endpoint id are passed, so you can scope any cleanup precisely.

```php
add_action( 'huxx_connect/admin/endpoint_deleted', function ( $api_id, $endpoint_id ) {
	error_log( sprintf(
		'[HuxxConnect] Endpoint %s/%s deleted',
		$api_id,
		$endpoint_id
	) );
}, 10, 2 );
```

Result (after deleting the `get_products` endpoint of `demo_api`):

```
[HuxxConnect] Endpoint demo_api/get_products deleted
```
<!-- /example:huxx_connect/admin/endpoint_deleted -->

### huxx_connect/admin/endpoint_saved

Fires after an endpoint configuration is created or updated. Fires on any persistence (admin save, import, migration, or programmatic write), not only from the admin screen.

**Type:** action · **Since:** — · **Source:** `src/Storage/EndpointRepository.php`

```php
do_action( 'huxx_connect/admin/endpoint_saved', $endpoint_id, $data );
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `$endpoint_id` | `int|string` | The endpoint database ID (on create) or slug (on update). |
| `$data` | `array` | The endpoint data. |

<!-- example:huxx_connect/admin/endpoint_saved -->
React whenever an endpoint is created or updated — for example, to warm your own cache or notify another system.

```php
add_action( 'huxx_connect/admin/endpoint_saved', function ( $endpoint_id, $data ) {
	error_log( sprintf(
		'[HuxxConnect] Endpoint "%s" saved (method: %s)',
		$endpoint_id,
		$data['method'] ?? 'GET'
	) );
}, 10, 2 );
```

Result (after saving the `get_products` endpoint):

```
[HuxxConnect] Endpoint "get_products" saved (method: GET)
```
<!-- /example:huxx_connect/admin/endpoint_saved -->

### huxx_connect/loaded

Fires after HuxxConnect has fully initialized.

**Type:** action · **Since:** — · **Source:** `src/Plugin.php`

```php
do_action( 'huxx_connect/loaded' );
```

<!-- example:huxx_connect/loaded -->
Fires once, after HuxxConnect has fully initialized. Use it as the safe point to wire up an integration that depends on HuxxConnect's helpers being available.

```php
add_action( 'huxx_connect/loaded', function () {
	if ( function_exists( 'huxx_api' ) ) {
		error_log( '[MyPlugin] HuxxConnect is ready; wiring up integration.' );
	}
} );
```

Result (on every page load once the plugin has booted):

```
[MyPlugin] HuxxConnect is ready; wiring up integration.
```
<!-- /example:huxx_connect/loaded -->

## Post Creator

### huxx_connect/post_creator/after_create

Fires after a post has been created by Post Creator.

**Pro** · **Type:** action · **Since:** 1.0.0 · **Source:** `src/Features/PostCreator/PostCreatorService.php`

```php
do_action( 'huxx_connect/post_creator/after_create', $post_id, $item, $config, $context );
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `$post_id` | `int` | The new post ID. |
| `$item` | `array` | The source API item. |
| `$config` | `PostCreatorConfig` | The Post Creator configuration. |
| `$context` | `array` | {@see HuxxConnectProSupportHookContext::build()}. |

<!-- example:huxx_connect/post_creator/after_create -->
Fires once a new post exists. Stamp the originating source id onto it so later runs (or your own reporting) can trace the post back to the feed:

```php
add_action( 'huxx_connect/post_creator/after_create', function ( $post_id, $item, $config, $context ) {
    // $item is the raw source row — e.g. a product from demo_api:get_products.
    update_post_meta( $post_id, 'source_product_id', $item['id'] ?? 0 );
}, 10, 4 );
```

Result: every post created from `demo_api:get_products` gets a `source_product_id` meta holding the product's `id`.
<!-- /example:huxx_connect/post_creator/after_create -->

### huxx_connect/post_creator/after_sync

Fires after a Post Creator sync completes.

**Pro** · **Type:** action · **Since:** 1.1.0 · **Source:** `src/Features/PostCreator/PostCreatorService.php`

```php
do_action( 'huxx_connect/post_creator/after_sync', $result, $context );
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `$result` | `RunResult` | Sync result with stats. |
| `$context` | `array` | {@see HuxxConnectProSupportHookContext::build()}. |

<!-- example:huxx_connect/post_creator/after_sync -->
Fires once, after the whole run finishes. `$result` is a `RunResult` with the tallies; `$context` carries `feature`, `api`, `endpoint`, plus `api_id`/`endpoint_id`. Log a summary line:

```php
add_action( 'huxx_connect/post_creator/after_sync', function ( $result, $context ) {
    error_log( sprintf(
        'Post Creator sync of %s finished: %d created, %d updated, %d skipped.',
        $context['endpoint_id'],
        $result->get_created(),
        $result->get_updated(),
        $result->get_skipped()
    ) );
}, 10, 2 );
```

Result (error log): `Post Creator sync of get_products finished: 12 created, 3 updated, 15 skipped.`
<!-- /example:huxx_connect/post_creator/after_sync -->

### huxx_connect/post_creator/after_update

Fires after a post has been updated by Post Creator.

**Pro** · **Type:** action · **Since:** 1.0.0 · **Source:** `src/Features/PostCreator/PostCreatorService.php`

```php
do_action( 'huxx_connect/post_creator/after_update', $post_id, $item, $config, $context );
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `$post_id` | `int` | The updated post ID. |
| `$item` | `array` | The source API item. |
| `$config` | `PostCreatorConfig` | The Post Creator configuration. |
| `$context` | `array` | {@see HuxxConnectProSupportHookContext::build()}. |

<!-- example:huxx_connect/post_creator/after_update -->
Fires after an existing post is rewritten. Use it to invalidate anything derived from that post — here, its object cache entry:

```php
add_action( 'huxx_connect/post_creator/after_update', function ( $post_id, $item, $config, $context ) {
    clean_post_cache( $post_id );
}, 10, 4 );
```

Result: each updated product post has its cache cleared so the next read reflects the fresh data.
<!-- /example:huxx_connect/post_creator/after_update -->

### huxx_connect/post_creator/before_delete

Fires before a post is deleted during full_sync.

**Pro** · **Type:** action · **Since:** 1.0.0 · **Source:** `src/Features/PostCreator/PostCreatorService.php`

```php
do_action( 'huxx_connect/post_creator/before_delete', $post_id, $unique_value, $source, $context );
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `$post_id` | `int` | The post being deleted. |
| `$unique_value` | `mixed` | The unique key value. |
| `$source` | `string` | The source identifier. |
| `$context` | `array` | {@see HuxxConnectProSupportHookContext::build()}. |

<!-- example:huxx_connect/post_creator/before_delete -->
Fires only during `full_sync`, just before a post that has dropped out of the feed is permanently deleted. It observes the deletion — it can't cancel it — so use it to record or archive:

```php
add_action( 'huxx_connect/post_creator/before_delete', function ( $post_id, $unique_value, $source, $context ) {
    error_log( "Post Creator deleting post {$post_id} (key {$unique_value}) from {$source}" );
}, 10, 4 );
```

Result (error log): `Post Creator deleting post 812 (key 42) from demo_api:get_products`
<!-- /example:huxx_connect/post_creator/before_delete -->

### huxx_connect/post_creator/before_sync

Fires when a Post Creator sync is about to begin.

**Pro** · **Type:** action · **Since:** 1.1.0 · **Source:** `src/Features/PostCreator/PostCreatorService.php`

```php
do_action( 'huxx_connect/post_creator/before_sync', $context );
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `$context` | `array` | {@see HuxxConnectProSupportHookContext::build()}. |

<!-- example:huxx_connect/post_creator/before_sync -->
A fire-and-forget signal emitted after validation passes but before any API work. `$context` carries the run's identifiers. Useful for telemetry:

```php
add_action( 'huxx_connect/post_creator/before_sync', function ( $context ) {
    error_log( 'Post Creator sync starting for ' . $context['api_id'] . ':' . $context['endpoint_id'] );
}, 10, 1 );
```

Result (error log): `Post Creator sync starting for demo_api:get_products`
<!-- /example:huxx_connect/post_creator/before_sync -->

## Builder Sync

### huxx_connect/builder_sync/after_sync

Fires after a collection sync completes (success or partial).

**Pro** · **Type:** action · **Since:** 1.0.0 · **Source:** `src/Features/BuilderSync/BuilderSyncService.php`

```php
do_action( 'huxx_connect/builder_sync/after_sync', $result, $context );
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `$result` | `array` | { |
| `$context` | `array` | {@see HuxxConnectProSupportHookContext::build()}. |

<!-- example:huxx_connect/builder_sync/after_sync -->
Fires once a collection sync finishes (success or partial). It is an observation point — log, purge caches, or notify; it cannot change what was written. `$result` carries `items_count`, `builders` (IDs written), and `error`.

```php
add_action(
    'huxx_connect/builder_sync/after_sync',
    function ( array $result, array $context ) {
        if ( 'demo_api' !== ( $context['api_id'] ?? '' ) ) {
            return;
        }

        $builders = ! empty( $result['builders'] ) ? implode( ', ', $result['builders'] ) : 'none';

        error_log( sprintf(
            '[demo_api] builder sync (%s): %d items written to %s%s',
            $context['trigger'] ?? 'manual',
            $result['items_count'],
            $builders,
            '' !== $result['error'] ? ' — error: ' . $result['error'] : ''
        ) );
    },
    10,
    2
);
```

Result (debug log after a manual Sync Now writing 30 products to Etch):

```
[demo_api] builder sync (manual): 30 items written to etch
```
<!-- /example:huxx_connect/builder_sync/after_sync -->

## OAuth

### huxx_connect/oauth/authorized

Fires after an OAuth authorization-code flow completes successfully.

**Pro** · **Type:** action · **Since:** — · **Source:** `src/Features/OAuth/OAuthCallbackHandler.php`

```php
do_action( 'huxx_connect/oauth/authorized', $api_id );
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `$api_id` | `string` | API identifier that was authorized. |

<!-- example:huxx_connect/oauth/authorized -->
Fires once the authorization-code exchange succeeds, so you can react to a freshly connected API — for example, kick off a first sync.

```php
add_action( 'huxx_connect/oauth/authorized', function ( $api_id ) {
	error_log( sprintf( '[HuxxConnect] OAuth connected for API "%s".', $api_id ) );

	if ( 'demo_api' === $api_id ) {
		// Warm the endpoint right after the user connects.
		wp_schedule_single_event( time() + 5, 'my_prime_demo_api_cache' );
	}
} );
```

Result: after the user authorizes `demo_api`, the log records the connection and a one-off event is scheduled to prime its cache.
<!-- /example:huxx_connect/oauth/authorized -->

### huxx_connect/oauth/token_expired

Fires when an OAuth token has expired and cannot be refreshed.

**Pro** · **Type:** action · **Since:** — · **Source:** `src/Features/OAuth/OAuthProvider.php`

```php
do_action( 'huxx_connect/oauth/token_expired', $api_id );
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `$api_id` | `string` | API identifier whose token expired. |

<!-- example:huxx_connect/oauth/token_expired -->
Fires when a token has expired and could not be refreshed — the next request will fail until the API is re-authorized. Use it to alert an admin.

```php
add_action( 'huxx_connect/oauth/token_expired', function ( $api_id ) {
	if ( 'demo_api' !== $api_id ) {
		return;
	}

	wp_mail(
		get_option( 'admin_email' ),
		'Action needed: reconnect demo_api',
		sprintf( 'The OAuth token for "%s" expired and could not be refreshed. Please re-authorize it in HuxxConnect.', $api_id )
	);
} );
```

Result: when `demo_api`'s token can no longer be refreshed, the site admin receives an email prompting them to reconnect the integration.
<!-- /example:huxx_connect/oauth/token_expired -->

### huxx_connect/oauth/token_refreshed

Fires after an OAuth access token is successfully refreshed.

**Pro** · **Type:** action · **Since:** — · **Source:** `src/Features/OAuth/OAuthFlowHandler.php`

```php
do_action( 'huxx_connect/oauth/token_refreshed', $api_id );
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `$api_id` | `string` | API identifier whose token was refreshed. |

<!-- example:huxx_connect/oauth/token_refreshed -->
Fires after an expired access token is silently renewed (via a refresh token or a fresh client-credentials request). This is an observation point — the token has already been stored.

```php
add_action( 'huxx_connect/oauth/token_refreshed', function ( $api_id ) {
	error_log( sprintf( '[HuxxConnect] OAuth token refreshed for API "%s".', $api_id ) );
} );
```

Result: each time HuxxConnect renews `demo_api`'s access token behind the scenes, a line is written to the log — useful for confirming the refresh loop is healthy.
<!-- /example:huxx_connect/oauth/token_refreshed -->

## Pagination

### huxx_connect/pagination/page_fetched

Fires after each page is fetched during pagination.

**Pro** · **Type:** action · **Since:** — · **Source:** `src/Services/PaginatedFetcher.php`

```php
do_action( 'huxx_connect/pagination/page_fetched', $page_number, $item_count, $api_id, $endpoint_id );
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `$page_number` | `int` | 1-indexed page number. |
| `$item_count` | `int` | Number of items on this page. |
| `$api_id` | `string` | API identifier. |
| `$endpoint_id` | `string` | Endpoint identifier. |

<!-- example:huxx_connect/pagination/page_fetched -->
Log a progress line as each page of a paginated fetch lands.

```php
add_action(
	'huxx_connect/pagination/page_fetched',
	function ( $page_number, $item_count, $api_id, $endpoint_id ) {
		error_log(
			sprintf(
				'[HuxxConnect] %s/%s page %d fetched — %d items',
				$api_id,
				$endpoint_id,
				$page_number,
				$item_count
			)
		);
	},
	10,
	4
);
```

Result (fetching `demo_api` / `get_products`, 30 items per page):

```
[HuxxConnect] demo_api/get_products page 1 fetched — 30 items
[HuxxConnect] demo_api/get_products page 2 fetched — 30 items
[HuxxConnect] demo_api/get_products page 3 fetched — 30 items
```

This fires after each page is retrieved and its items are merged; it observes progress only and cannot change what is fetched — use `huxx_connect/pagination/next_value` for that.
<!-- /example:huxx_connect/pagination/page_fetched -->