benecaster_download_logged
Fires after a download event is successfully written to the download log.
Use this hook to react to confirmed download activity — for example, to dispatch a background job that recalculates show stats, write a secondary audit record, or send a notification. This hook fires only when a log row was actually persisted; it does not fire when the [benecaster_download_log_entry](/hooks/benecaster_download_log_entry/) filter returned an empty array. Use [benecaster_download_redirected](/hooks/benecaster_download_redirected/) if you need a hook that fires on every proxied request regardless of whether logging occurred.
The `$log_entry` array contains the full row as persisted:
| Key | Type | Description | |—|—|—| | `episode_id` | int | Episode post ID | | `show_id` | int | Show post ID the episode belongs to | | `token_id` | int | Token record ID used to authorize the request | | `user_id` | int | WordPress user ID (`0` if unauthenticated) | | `tier_slug` | string | Subscriber tier at the time of download | | `ip_hash` | string | SHA-256 hash of the requester’s IP address | | `byte_range` | string\|null | Value of the `Range` header, or `null` | | `client_app` | string | Detected podcast app label | | `country_code` | string\|null | ISO 3166-1 alpha-2 country code, or `null` | | `region_code` | string\|null | ISO 3166-2 region code, or `null` | | `downloaded_at` | string | UTC datetime (`Y-m-d H:i:s`) when the row was written |
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
$episode_id |
int |
— | Episode post ID that was downloaded |
$user_id |
int |
— | WordPress user ID of the subscriber; 0 for unauthenticated requests |
$log_entry |
array |
— | The full log row as persisted to the database |
Examples
Recalculate show stats in the background
add_action(
'benecaster_download_logged',
function ( int $episode_id, int $user_id, array $log_entry ): void {
wp_schedule_single_event(
time(),
'my_plugin_recalculate_show_stats',
[ $log_entry['show_id'] ]
);
},
10,
3
);Write a secondary audit record for a specific tier
add_action(
'benecaster_download_logged',
function ( int $episode_id, int $user_id, array $log_entry ): void {
global $wpdb;
if ( 'pro' !== $log_entry['tier_slug'] ) {
return;
}
$wpdb->insert(
$wpdb->prefix . 'my_compliance_log',
[
'episode_id' => $episode_id,
'user_id' => $user_id,
'country_code' => $log_entry['country_code'],
'downloaded_at' => $log_entry['downloaded_at'],
],
[ '%d', '%d', '%s', '%s' ]
);
},
10,
3
);Notes
Fires synchronously before the redirect response is sent. Keep callbacks fast.
For non-trivial processing (external API calls, queue dispatch), use
wp_schedule_single_event() or similar rather than blocking here.
$user_id of 0 indicates a request that passed token validation but has no
associated WordPress account (e.g. a public feed download). Check
$log_entry['token_id'] for the token that authorized it.
The $log_entry array reflects the row as actually persisted, including any
modifications made by the benecaster_download_log_entry filter upstream.
