wp_insert_post fires before post meta is reliably saved, while wp_after_insert_post runs after the full save cycle. If your AI callback hooks into both without a guard, you get a double-fire on every save that burns tokens, corrupts revisions, and silently fails under batch operations. Use a single hook with a post-status gate, not two hooks hoping WordPress keeps your order.
Your AI plugin just generated the wrong summary. Twice. The user saved a draft, your callback fired on wp_insert_post, sent the content to your GPT endpoint, stored the result. Then wp_after_insert_post fired, your hook ran again, and the second call overwrote the first with a different token count. The revision history shows two AI calls per save. Your logs show double the billing. Nobody filed a bug because the content “looks fine.”
This is the hook conflict pattern that the WordPress 6.8 AI hook announcements never documented. And it breaks exactly the kind of plugin you are building.
## The Two Hooks and Why They Exist
WordPress has two moments when a post insertion matters to you as a plugin architect:
**wp_insert_post** fires inside wp_insert_post() itself, right after the row hits the database but before all meta operations complete. It gives you the post ID, the post data, and a boolean indicating whether this is an update. Most tutorials treat this as “the” hook for post-saving logic.
**wp_after_insert_post** fires after the entire save lifecycle finishes. Post content, post meta, terms, revisions, all of it. It was introduced in WordPress 5.6 specifically to give plugins a reliable moment where everything is persisted.
The problem: both hooks pass the same $post object and $update boolean. They look identical from your callback's perspective. If your registration code does not explicitly pick one and block the other, you get called twice.
## Where the Double-Fire Actually Happens
Here is the trap. Most plugin architects register their AI callback like this:
“`php
add_action( ‘wp_insert_post', ‘my_ai_enrich_callback', 10, 3 );
add_action( ‘wp_after_insert_post', ‘my_ai_enrich_callback', 10, 3 );
“`
The reasoning is defensive: “I'll catch it regardless of which hook fires first.” But WordPress calls both. Every single save. The wp_insert_post fires during the function, then wp_after_insert_post fires after it returns. You are not catching one or the other. You are catching both, sequentially, with the same callback.
**What happens on a normal save:**
1. User clicks “Save Draft”
2. wp_insert_post fires. Your AI callback runs. Token burn: ~1,200 tokens.
3. Post meta saves complete. Revisions created.
4. wp_after_insert_post fires. Your AI callback runs again. Token burn: ~1,200 tokens.
5. User sees one save. Your logs show two API calls.
**What happens on a REST API batch (common in AI block editors):**
The block editor saves content via wp-json/wp/v2/posts/{id}. REST API endpoints call wp_insert_post() internally. If your plugin also hooks into the REST endpoint separately, you can get a triple fire: once from your REST callback, once from wp_insert_post, once from wp_after_insert_post.
This is the undocumented interaction that breaks AI block editors and custom GPT integrations in production.
## The Post-Meta Timing Landmine
There is a second problem that makes this worse. If your AI callback needs to read custom post meta that was just saved (like an AI model selection, a prompt template ID, or a content source flag), timing matters:
– On wp_insert_post: meta from the current save may not be available yet. get_post_meta() returns stale data or empty values.
– On wp_after_insert_post: meta is reliably persisted. get_post_meta() returns correct values.
So if you chose wp_insert_post to “fire early,” your AI callback is reading wrong meta. If you chose wp_after_insert_post for correctness, but also registered on wp_insert_post defensively, your first call reads wrong data and your second call reads correct data. The first call's AI output is based on stale context. The second overwrites it with correct-context output. Your revision history stores both. The user never sees the bad one, but your billing saw it.
## The Fix: One Hook, One Guard
Stop registering on both hooks. Pick one. The correct one for AI callbacks is wp_after_insert_post, because you need persisted meta and complete post data.
“`php
/**
* Single hook registration for AI content enrichment.
* Only on wp_after_insert_post. Never wp_insert_post.
*/
add_action( ‘wp_after_insert_post', ‘my_ai_enrich_callback', 20, 3 );
function my_ai_enrich_callback( int $post_id, \WP_Post $post, bool $update ): void {
// Guard: skip autosaves, revisions, and non-published statuses.
if ( wp_is_post_revision( $post_id ) || wp_is_post_autosave( $post_id ) ) {
return;
}
// Guard: only run on your target post type.
if ( ‘post' !== $post->post_type ) {
return;
}
// Guard: prevent re-entry if this callback triggers another save.
static $running = [];
if ( isset( $running[ $post_id ] ) ) {
return;
}
$running[ $post_id ] = true;
// Now safe to read meta and call your AI endpoint.
$model = get_post_meta( $post_id, ‘_ai_model', true );
$result = call_your_ai_endpoint( $post->post_content, $model );
update_post_meta( $post_id, ‘_ai_summary', $result );
unset( $running[ $post_id ] );
}
“`
**The re-entry guard matters more than you think.** If your AI callback calls update_post_meta(), WordPress does not re-fire wp_after_insert_post for meta-only updates. But if your callback modifies the post itself (updates title, content, or status), it will re-fire. The static $running array catches this and prevents infinite loops.
## The Priority Number Is Not Arbitrary
Notice the 20 priority in the registration. Here is why:
– Priority 10 (default): Runs before other plugins that hook at default priority. Safe if you are the only AI plugin, dangerous if you are not.
– Priority 20: Runs after most default-priority hooks. Gives other plugins (SEO, caching, analytics) time to finish their meta writes first. Your AI callback then reads fully updated state.
– Priority 5: Runs before almost everything. Useful only if you are injecting content that other hooks depend on.
For AI enrichment callbacks that read meta written by other plugins, priority 20 is the sweet spot. You get complete data. Other plugins get their writes in first.
## WordPress 6.8 Specific Behavior
WordPress 6.8 tightened some internal save logic around the block editor's REST-based persistence model. The key change relevant to AI hooks:
The block editor now batches meta updates through a single wp_after_insert_post pass instead of individual meta calls during content save. This means:
1. Your wp_after_insert_post callback sees all meta, including meta set by the block editor's own save routine.
2. If your AI callback triggers a post save (via wp_update_post()), the block editor's save handler runs again. This is the re-entry scenario.
3. wp_insert_post still fires during the initial REST request. If you registered there too, you are still double-firing.
The 6.8 changes do not fix the double-fire problem for you. They make the wp_after_insert_post timing more reliable, which is good. But the responsibility to register on exactly one hook remains yours.
## Real-World Integration Pattern for GPT Plugins
If you are building a custom GPT integration for WordPress, here is the pattern that works in production:
**1. Register once on wp_after_insert_post with priority 20.**
**2. Gate on post type, status, and autosave.** Your AI callback should never fire on nav_menu_item, revision, or attachment post types.
**3. Use a transient lock for concurrent requests.** If two browser tabs save the same post simultaneously, your callback runs twice. Use set_transient( 'ai_lock_' . $post_id, 1, 60 ) as a mutex.
**4. Store your AI result in custom meta, not post content.** Modifying $post->post_content from inside wp_after_insert_post triggers a re-save. Store in _ai_summary, _ai_tags, _ai_sentiment instead.
**5. Log every API call with the hook that triggered it.** Add a filter or constant that marks which hook path your callback took. When debugging double-fires, this is the first thing you need.
## What About the Block Editor's Auto-Save?
Auto-saves fire their own wp_insert_post call. They also fire wp_after_insert_post if the auto-save creates a new post record (which it does for post IDs, not for revisions in the traditional sense). Your autosave guard must check both:
“`php
if ( defined( ‘DOING_AUTOSAVE' ) && DOING_AUTOSAVE ) {
return;
}
if ( wp_is_post_autosave( $post_id ) ) {
return;
}
“`
WordPress does not consistently set DOING_AUTOSAVE for block editor auto-saves triggered via REST. The wp_is_post_autosave() check is more reliable. Use both for safety.
## Related Reading
If you are also dealing with the latency implications of AI hooks on WordPress queries, check our deep dive on AI Content Hooks vs WP_Query: The Real Latency Tax on WordPress 6.8. It covers the performance side of the same problem.
## Frequently Asked Questions
### Can I use save_post instead of wp_after_insert_post for my AI callback?
save_post is older and less reliable for AI use cases. It fires before post meta is saved for new posts, which means your AI callback reads incomplete data on first save. wp_after_insert_post is the recommended replacement. WordPress core team has explicitly suggested migrating from save_post for post-meta-dependent logic.
### My AI callback works fine on single saves but breaks on REST API saves. What gives?
The REST API save path calls wp_insert_post() with different internal flags. If your callback checks for $_POST data or wp_verify_nonce() on the REST path, those checks fail silently. For REST-compatible callbacks, check rest_do_request() context or use wp_is_rest_request() to branch your validation logic.
### How do I prevent my AI callback from firing when a cron job updates posts?
Check wp_doing_cron() at the top of your callback. If your AI enrichment should only fire on user-initiated saves (not WP-Cron scheduled updates), return early when wp_doing_cron() is true.
### Is there a way to batch AI calls instead of firing per-save?
Yes, and you should. Use wp_schedule_single_event() inside your callback to defer the AI call, then batch pending items on a 30-second cron interval. This reduces API calls from N-per-save to 1-per-batch. For block editors that auto-save every 60 seconds, this alone cuts your token bill by 80% or more.
### My plugin uses both wp_insert_post and wp_after_insert_post. Which one should I remove?
Remove the wp_insert_post registration. Keep wp_after_insert_post. There is no scenario where a plugin architect building AI integrations needs the earlier hook. The later hook gives you complete data, correct meta, and avoids the double-fire trap.
