Action Hook since 1.2.0

wp_insert_post

Fires immediately after a post is inserted or updated in the database

Description

wp_insert_post looks like save_post but fires from every wp_insert_post() call, including programmatic inserts that never touch the block editor.

When it runs

Inside wp_insert_post(), right after the database write, just before save_post fires.

Signature

do_action( 'wp_insert_post', int $post_id, WP_Post $post, bool $update );

Parameters

$post_id int — Inserted/updated post ID.
$post WP_Post — Post object.
$update bool — True when updating an existing post.

Examples

Basic

add_action( 'wp_insert_post', function( $post_id, $post, $update ) {
    if ( 'book' !== $post->post_type || $update ) {
        return;
    }
    wp_mail( get_option( 'admin_email' ), 'New book added', get_the_title( $post_id ) );
}, 10, 3 );

Email an admin only when a brand-new book post is created.

Common Use Cases

Notify on new post creation (not updates)
React to programmatic/import inserts
Sync newly created posts to an external system

Common mistakes

Using wp_insert_post to detect edits from the editor UI — save_post is the more common choice there; this fires for ALL inserts including imports

Related hooks

Works with save_post
Works with transition_post_status

FAQ

Should I use wp_insert_post or save_post?

Use save_post for editor-driven saves; use wp_insert_post if you also need to catch posts created programmatically outside the editor.

Source: wp-includes/post.php

Group wizard

One session: this hook, then each related_hooks entry. Walk it and tell us what to change.

wp_insert_post → save_post → transition_post_status

functions.php — wp_insert_post

functions.php

<?php
/**
 * Practice: hook into wp_insert_post
 */
add_action( 'wp_insert_post', function( $post_id, $post, $update ) {
	// Write your callback here.

} );

Group tour

wp_insert_post · Hook 1 of 3 · Step 1 of 6

Meet wp_insert_post

Fires immediately after a post is inserted or updated in the database

wp_insert_post looks like save_post but fires from every wp_insert_post() call, including programmatic inserts that never touch the block editor.

type actionphase datasince 1.2.0source wp-includes/post.php

do_action( 'wp_insert_post', int $post_id, WP_Post $post, bool $update );

add_action( 'wp_insert_post', function( $post_id, $post, $update ) {
    if ( 'book' !== $post->post_type || $update ) {
        return;
    }
    wp_mail( get_option( 'admin_email' ), 'New book added', get_the_title( $post_id ) );
}, 10, 3 );

PHP wp_insert_post · Hook 1 of 3 · Step 1 of 6

Practice the wp_insert_post WordPress action hook in our interactive sandbox — a VS Code-style editor with a step-by-step wp_insert_post tutorial, add_action exercises, and instant feedback. No local WordPress install required.