Key Takeaways: Use the Hook vs REST-AI matrix below on every headless WordPress 6.8 build. Pick hooks when the trigger lives inside WordPress (save_post, wp_after_insert_post, add_attachment). Pick a custom REST-AI endpoint when the trigger lives in your Next.js or Astro frontend, build step, or edge runtime. The single biggest mistake in 2026 is registering the same callback on both wp_insert_post and wp_after_insert_post; that burns tokens twice per save and corrupts the audit trail.
You finally got headless WordPress humming. Next.js or Astro renders content at the edge, your decoupled stack feels modern, and the content team is happy in the Gutenberg editor. Then marketing drops a request: “Add AI summaries to every post, AI alt text on every image, and an AI rewrite button inside our custom block.”
You pause. Should the AI live inside WordPress via PHP hooks, or should your frontend hit a custom REST-AI endpoint? Every tutorial picks one side and never explains the other. Three production builds later, here is the comparator I wish existed on day one. The matrix below is what separates a clean headless AI stack from a debug-every-Monday nightmare.
The Question Senior Leads Get Asked Every Sprint
Junior devs assume headless means “frontend owns everything.” So they bolt a custom REST-AI endpoint onto WordPress and call it from React. It works. Then it silently double-fires, leaks API keys into the bundle, or breaks every time WordPress 6.8 changes how the block editor persists meta.
Senior full-stack devs ask a different question: where does the trigger live? That single question collapses weeks of architecture debate into a two-minute decision. This comparator is built around that question. By the end, you will have a matrix you can paste into your team's runbook.
The Two Architectures, Mapped
Architecture A: AI Generation Through WordPress Hooks
You register a PHP callback on save_post, wp_after_insert_post, or add_attachment. The callback calls OpenAI, Anthropic, or a local LLM. The output lands in post meta or block markup. Your Next.js or Astro frontend never sees the provider call; it only reads the result through the next REST response.
- Trigger surface: editor saves, publish transitions, media uploads, cron, block render
- Auth: reuses WordPress nonce and capability checks for free
- Async model: synchronous by default, defer to Action Scheduler for heavy work
- Failure handling:
wp_send_json_error()in the editor, silent retry queue in production
Architecture B: Custom REST-AI Endpoint
You call register_rest_route(), expose /wp-json/your-plugin/v1/generate, and let your headless frontend or build script call it. The provider key lives in wp-config.php. The request shape, streaming, and error UX are owned by the frontend layer.
- Trigger surface: frontend user actions, build-time batch jobs, scheduled cron in the frontend layer
- Auth: you write
permission_callback, often Application Passwords or JWT - Async model: you control SSE, chunked transfer, polling, webhooks
- Failure handling: structured JSON shaped for your React error boundary
The Hook vs REST-AI Decision Matrix (Steal This)
Use this table on every code review. If you cannot defend your choice with one of these rows, you are guessing.
| Scenario | Pick Hooks | Pick REST-AI Endpoint |
|---|---|---|
| Auto-summarize or auto-tag on save | Yes | No |
| Generate alt text on media upload | Yes | No |
| User clicks “Rewrite” inside a custom block | No | Yes |
| Build-time batch generation for 500 posts | No | Yes |
| Streaming tokens into a Next.js UI | No | Yes (SSE or chunked) |
| Provider key must never reach the frontend bundle | Yes | Yes (server-side route is safe) |
| Compliance requires audit log inside WordPress DB | Yes | Possible, more code |
| Frontend runs on edge runtime (Astro, Vercel Edge) | No | Yes |
| AI fires during scheduled publish from cron | Yes | No |
| AI fires when a visitor submits a form | No | Yes |
The matrix is short on purpose. If your scenario is not in the table, the real question is who clicked the button? Editor clicked it: hook. Visitor clicked it: REST. Build pipeline clicked it: REST.
The Counter-Intuitive Bit: Hooks Win Most “Frontend” Features
Most full-stack devs reach for a custom REST endpoint the moment Next.js or Astro touches AI. Their reasoning: “Frontend owns the UI, frontend owns the call.” That instinct is wrong roughly 70% of the time.
Hooks give you free auth, free capability checks, and a free audit trail. The most expensive bug in 2026 headless builds is still the wp_insert_post double-fire trap that we documented in detail. Registering the same callback on both wp_insert_post and wp_after_insert_post is the single most common cause of surprise token bills and corrupted revision histories. The fix is mechanical: pick one hook, add a re-entry guard, and move on.
A heuristic that saves hours: if the AI work is a consequence of content already saved inside WordPress, hooks win. If the AI work is initiated by a visitor or by a build pipeline outside WordPress, REST wins. That is the whole game.
Why WordPress 6.8 Changes the Calculus
Three things shifted in 6.8 that affect this choice. First, custom REST routes now require an explicit permission_callback; without it, the route returns 403 by default. That is a security win, but it also means more boilerplate for the REST path. Second, the block editor batches meta updates through a single wp_after_insert_post pass, which makes hook timing more predictable. Third, application passwords are now stable across page-cache TTLs, which makes the REST auth story less painful than it was in 6.5.
Net effect: hooks got more reliable, REST got more secure. The decision still belongs to trigger ownership, but the costs on each side moved toward parity. If you want a deep read on the security side, the insecure code patterns that wreck plugins in five seconds is a good complement.
The Hybrid Pattern Real Teams Ship
In production, you do not pick one. You split by trigger type. Here is the pattern that survives code review:
- Hook layer handles background generation tied to content state. Alt text on upload, SEO summaries on publish, translation on scheduled post. All of it is consequence work. All of it runs in PHP, with no key in the frontend bundle.
- Custom REST-AI endpoint handles interactive user features. The “rewrite this paragraph” button, the “summarize on demand” action, the build-time batch that fills 500 product descriptions. All of it is initiation work. All of it streams, batches, or rate-limits cleanly.
This split mirrors how WordPress itself works: writes go through hooks, reads go through REST. Do not fight the architecture. If you are new to headless in general, our headless WordPress with Next.js guide and the block markup export piece on FSE block markup to React are worth a read first.
Implementation: Two Working Skeletons
Hook Skeleton (Auto Alt Text on Media Upload)
add_action( 'add_attachment', function ( $attachment_id ) {
if ( wp_is_post_revision( $attachment_id ) ) {
return;
}
$url = wp_get_attachment_url( $attachment_id );
$alt = your_ai_provider_generate_alt( $url );
if ( is_wp_error( $alt ) ) {
update_post_meta( $attachment_id, '_alt_generation_retry', time() );
return;
}
update_post_meta( $attachment_id, '_wp_attachment_image_alt', sanitize_text_field( $alt ) );
}, 20 );REST-AI Skeleton (On-Demand Rewrite from Next.js)
register_rest_route( 'myapp/v1', '/rewrite', [
'methods' => 'POST',
'permission_callback' => function ( $req ) {
return current_user_can( 'edit_posts' )
&& wp_verify_nonce( $req->get_header( 'x_wp_nonce' ), 'wp_rest' );
},
'callback' => function ( $req ) {
$post_id = (int) $req->get_param( 'post_id' );
$text = (string) $req->get_param( 'text' );
$result = your_ai_provider_rewrite( $text );
return rest_ensure_response( [ 'result' => $result ] );
},
] );For streaming, swap the callback body for a text/event-stream response with ob_flush(); flush(); per chunk. On the Next.js side, consume with response.body.getReader(). On Astro, the same pattern works inside a server endpoint. For a full streaming walkthrough, the 300ms decision deep dive has working code.
Security Footnote: The One Line That Saves You
If you expose an AI endpoint publicly, your permission_callback is the only wall between an attacker and your provider bill. WordPress 6.8 tightened defaults, but the callback is still your responsibility. The three checks you always want: validate origin, validate capability, validate rate. The official WordPress REST API custom endpoints documentation is short and worth re-reading every quarter. For a real-world cautionary tale, the breakdown of the Jetpack REST API sanitization flaw shows how a missing check turned into admin takeover.
Frequently Asked Questions
Can I use both hooks and a custom REST-AI endpoint in the same plugin?
Yes, and most production plugins do. Hooks handle save-time work; REST handles runtime and build-time features. Keep them in separate classes to avoid coupling.
Where should I store the AI provider API key?
In wp-config.php as a constant, never in the database and never in the frontend .env. Both hook and REST approaches can read it safely server-side.
How do I stream tokens from OpenAI back to a Next.js frontend?
Use a custom REST-AI endpoint with text/event-stream or chunked transfer. Hooks return synchronously, which kills long streams under load.
Does WordPress 6.8 change anything specific for AI hooks?
Yes. Tighter REST defaults and a more granular wp_after_insert_post lifecycle. Plan callbacks around save phases, not just the final save. The 6.8 shortcode migration code fix post covers the related lifecycle changes.
Which path works best with Astro's static build?
Custom REST-AI endpoint, called from your build script. Astro compiles at build time and your CI step fetches AI output, then bakes it into static HTML. Hooks assume a runtime WordPress context that static builds lack.
How do I keep my AI callback from double-firing on save?
Register on wp_after_insert_post only, with a priority around 20, plus a static re-entry guard. Do not register on wp_insert_post at the same time. Full code and reasoning in the double-fire trap post.
Your Next Move
Stop treating the hook vs REST-AI choice as a religion. Treat it as routing: who owns the trigger, who owns the UX. When the trigger lives inside WordPress, hooks. When the trigger lives in your Next.js or Astro layer, REST. Senior teams ship both; junior teams argue about it for a sprint.
Want the production-ready starter plugin (hook layer + REST route + audit log) sent to your inbox? Drop your email below and I will send the full skeleton with test fixtures, plus the latency numbers from our AI hook vs WP_Query benchmark.
External references: WordPress REST API custom endpoints and Next.js data fetching patterns.
